search

justinwalsh / daux.io

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.
daux.io
4.54k stars 526 forks source link

Numeric folder names cause some issues #190

Closed camfindlay closed 10 years ago

camfindlay commented 10 years ago

Hi there, first a quick hello - liking the look of daux in particular I'm considering it for powering documentation for an open source web framework and cms. The one issue I have run into is that we have technical docs for numbered versions of our software "3.1", 3.0" etc

When I set the folder structure up like

docs --en ----3.1 ------01_content_here ----3.0

I find that the folder name doesn't show in the URL or in the menu.

If I prefix the versioned folders with a word, everything works fine (however our end goal is to have the version numbers in our URL http://somedocs.com/en/3.1/content_here/). eg Test3.1, Test3.0 etc

If I prefix the versioned folder with the sort order eg 01_3.1 the folder shows up in the menu but cannot be interacted with, I cannot drill down into it.

It raises perhaps another higher level question, given this it a tool for technical docs, how might we handle docs for different versions of software in a nice way within daux?

I happen to like how laravel do there version switching http://laravel.com/docs (though I don't like that the switch doesn't change the URL).

Perhaps a feature such as that set in the config for multi-language could be created "multi-version" which can be passed numeric folders and names.

This would be a welcome addition :)

dkisselev commented 10 years ago

Hey Cam,

This issue is a repeat of #102, but I've had no time to actually work on Daux, so disregard my comment about Daux 1.0

Depending on when you first installed Daux, the issue with using numbers in the doc name may now be fixed by a merge that I did this morning (#184)

It looks like @codeKonami managed to put together a partially-working solution for having multiple Projects with their own structure, but never submitted a PR.

Closing to concentrate any related discussion into #102

camfindlay commented 10 years ago

Good to hear, though I just pulled latest changes and now getting a Notice: Undefined variable: link in /Users/user/Sites/docs/libs/live.php on line 31error.

The git repo related stuff that @codeKonami has done looks interesting. I have also been playing with github's gollum wiki - not quite as nice to look at but the idea that an edit triggers a git commit is quite useful for working on technical documentation as a technical writer.

codeKonami commented 10 years ago

Unfortunately I never had the chance to work on this idea much further than a ugly hack. Maybe in the future :)

dkisselev commented 10 years ago

Oops, probably should have tested more thoroughly before merging. I'll revert the changes for now so the live daux site works, and ask the author of that PR to fix