

Daux.io, a simple documentation generator - bpierre
http://daux.io

======
RyanZAG
_" You must use the .md file extension for your files. Also, you must use
underscores instead of spaces."_

Why? Are we still using MSDOS or something?

~~~
martin-adams
There's probably no technical reason why other than design choice. It may be
related to cleaner URLs omitting the %20 encoding.

However, hyphens would probably have been a better choice for URLs as Google
treats them as individual words as opposed to one long keyword.

~~~
exceptione
Also, hyphens save us an additional <shift>-key press. Hardly on topic, but my
advise is to require underscores only when there is absolutely no alternative.
Which is almost never the case.

~~~
justinwars
The forced .md and underscores was mostly for speed of development on the
first version of Daux. I agree it is a bit arbitrary and I plan on making the
requirements a bit less strict in the future.

------
ciokan
[https://github.com/justinwalsh/daux.io/blob/master/index.php](https://github.com/justinwalsh/daux.io/blob/master/index.php)
Seriously. Pick a template engine at least. They're around for quite some
time.

PHP & Node? Pick one. Don't make it a pain to even install.

~~~
gramsey
> PHP

> Pick a template engine at least.

There's a great one for PHP, it's called PHP.
[https://news.ycombinator.com/item?id=3821125](https://news.ycombinator.com/item?id=3821125)

------
sciurus
The feature "No Build Step" translates to "require your webserver to run PHP
to render your documentation every time it's accessed".

~~~
justinwars
This is completely true, and I started a Github issue to create an optional
build script to generate a static set of files that could be deployed to S3,
Github Pages or something similar.
[https://github.com/justinwalsh/daux.io/issues/6](https://github.com/justinwalsh/daux.io/issues/6)

------
mholt
Way cool. Not sure I'm a fan of the syntax-highlighted code snippets to the
right and in black text on the dark blue background though. Might like to see
it closer to the content, and with more contrast.

~~~
justinwars
If your not a fan of the code floating, that can be disabled. We are working
on getting some better code styles as well that should fix the contrast issue.

------
slajax
I'd like to see this combined with swagger:
[https://developers.helloreverb.com/swagger/](https://developers.helloreverb.com/swagger/)

~~~
justinwars
Interesting idea. I will look into what some possible options are. In the mean
time I create a Github issue to track the request:
[https://github.com/justinwalsh/daux.io/issues/13](https://github.com/justinwalsh/daux.io/issues/13)

------
fernly
I suppose "daux" is meant to be pronounced "docks" but a French-speaker would
say "doh!" like Homer Simpson.

Trivia aside, the front page does nothing to make the purpose or advantages
clear. What is "custom documentation"? (Is there another kind?) What is the
advantage of "on the fly"? (As opposed to the typical "make doc".)

Is there some way to create a multi-level hierarchy within the
"01_Getting_Started.md" filename convention? Is the filename structure the
_only_ way to indicate structure? (If so, a trivial structure change turns
into a nontrivial exercise of renaming files and getting git or svn to accept
renamed files as logically unchanged.) Is there a way to cross-reference
(link) between files? Is there a way to output in PDF, or any other format?

------
bhauer
This is very nice. Well done! I especially like the clean default styles.

One minor nit: the "fork me on Github" is superimposed over the scrolling
pane, so it's not possible to grab the scroll tack. That is, I can only scroll
via my mousewheel until the tack is past the fork overlay.

~~~
justinwars
Thanks! We will be pushing a fix for the scrollbar issue.

------
slajax
I used something very similar a few years ago. I think it was called dox.js.

Whats the story on the super similar name and ui? Is it the same thing? I'm
not trolling, I'm curious if they are related cause it was a great doc system
IMO.

~~~
justinwars
Wow, we even looked around when naming Daux to make sure there wouldn't be any
conflicts. I took a look at the dox project and I think we are going to be ok.
It looks to be a significantly different approach.

------
sergiotapia
Feedback: If I click the middle mouse button on the documentation here
[http://daux.io/Getting_Started](http://daux.io/Getting_Started) I get the
scroller icon thingy appear. Then I can scroll by moving the mouse right or
left and make the content dissapear at which point I go far enough and it
bounces back.

This _exact_ same effect happens on Outlook.com if you want to take a look at
reproducing it there as well.

~~~
pests
It appears there is more content to the right and you are simply scrolling the
page (moving the view opposite to direction of mouse movement) and once you
hit the edge it seems to invalidate the drag or something similar.

This is just from playing with it; I haven't had time to check the source yet.

~~~
justinwars
I have heard some people having issues with horizontal scrolling, I am still
trying to get to the bottom of this.

------
nwh
Please kill the orphans in the "features" section —
[http://i.imgur.com/mbJ5bX8.png](http://i.imgur.com/mbJ5bX8.png)

------
sohooo
There's also flatdoc
[http://ricostacruz.com/flatdoc/](http://ricostacruz.com/flatdoc/) which
renders the markdown file on the client side ('marked' js parser), so no
server-side stuff is needed.

------
exceptione
I like the looks. My suggestion would be to distribute it as a single phar-
archive (and to allow for hyphens).

------
robinduckett
Why does this need PHP?

~~~
Wilya
Because it's written in PHP ?

~~~
IanCal
It's documentation. Why is it not static?

~~~
ben336
Its generating static files from MD files. That requires a server-side
language of some type. The weird part is that it appears to use both Node and
PHP.

------
akldjlafkjalfk
with no mousewheel you have problems to scroll. Using the scrollbar is made
impossible by overlapping … : (

------
ronaldsvilcins
Nice!

