Daux.io, a simple documentation generator | Hacker News Reader

Daux.io, a simple documentation generator

daux.io

107 pointsbpierre31 comments

"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?

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.

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.

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.

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.

> 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

I agree I should have used a template engine. I wrote most of this with the idea that it would be a proof of concept but ended up turning into something I felt others would still benefit from. It's still simple enough to get around the code without a template engine, but I would love to refactor one in.

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

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

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.

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.

I'd like to see this combined with swagger: https://developers.helloreverb.com/swagger/

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

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?

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.

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

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.

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.

Feedback: If I click the middle mouse button on the documentation here 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.

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.

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

Please kill the orphans in the "features" section — http://i.imgur.com/mbJ5bX8.png

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

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

Why does this need PHP?

Because it's written in PHP ?

It's documentation. Why is it not static?

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.

Then why does it also need Grunt.js?

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

Nice!

Reply on news.ycombinator.com