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's Issues

Clean up theming so that multiple templates can added and chosen

The way I see this working out would be that the index page loads up the options, finds the name of the template it wants to use (which would be stored in /templates/template-name), then "includes" the index.php from that template and passes it an array of the page title, modified date/time, main HTML content, navigation tree, and any other content that appears on a page.

This way, different themes can be written by any designer and just dropped into the templates folder. Then edit your config.json with a template name and you're set.

Just looking to get some feedback and gauge interest before I start working on it.

Wrapped lines using single breaks do not render correctly

Reported by reddit user:

Double-linebreak spacing is used so that documents can be written by humans to fit within 80 characters without necessarily introducing rendered formatting issues. Remember, markdown is supposed to be a fully human-readable source document. Here's a great example of why single-linebreak formatting is wrong, straight from your documentation: http://cl.ly/image/1o2A3k421C2z

Source

Code blocks pop out into right hand gutter when window is above a certain size

Using FF 22.0 on Win 7

Code blocks render properly when browser window is below about 1150 px wide. Above that, a blue gutter appears on the right hand side of the screen and code blocks are displayed there rather than in the normal content section. See screen shot.

Licensing ?

Hi,

I don't see any License file or Open source mention, so is it a Free Software ?

Not rendering line breaks to separate lists

I have a series of lists one after the other, divided into relevance. Daux's Markdown parser seems to not be reading or applying my line breaks, creating separate lists.

My Markdown clearly has line breaks separating the lists but when rendered in Daux:

It creates one long list, instead of 3 shorter ones.

Support Swapper API documentation generation

From HackerNews user:

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

Source

Folder depth

Hello,

I think you should be able to create a multilevel documentation, for example if you have a folder inside a folder, it should handle depth properly with submenus.

the php requirement

the requirement for php seems odd...

You can run the docs locally using Grunt.js I assume you are familiar with how to use Grunt and have the latest version of PHP 5.4 installed which is able to run a webserver.

why the choice for a second server? Not that php is bad, I'm just wondering why you have added an extra dependency, when gruntJS runs on node, you could easily use a server module that works on nodejs.

I'm just saying that because I am not a php developer and don't have php installed. I understand many will have it installed but it's an extra dependency you can do without.

Can not find files contain Chinese, Japanese, Korean in path

If a md file path contains CJK(Chinese, Japanese, Korean) character, the file can been seen in the left menu, but when click the link, it says there's no such page.

Suggestion

This looks very cool. At work we have just put a bit of effort into building an internal tool to do something similar. A key feature that forced us to do our own was the desire to include 'private' comments in our docs. That is - rather than have a completely separate system for developer notes, implementation details and and so - we wanted a system that allowed us to mark some elements of our markdown files as 'private'. These could be viewed by our team on our 'private' repo - but the 'outside' world saw the simpler version.

I would have been quite happy paying a small amount for a tool that included this feature - but couldn't find one. Just offered here as a suggestion.

Multi level ul/ol

Demo

• list1
• list2
  1. sub-list
  2. sub-list
• list3

When i type multi-level ul/ol tag like this, it will converted two br tag between list2 and 1. sub-list

Is there any solution? Thinks~ & I love daux ^!^

Adding a database

What would it take to connect daux.io to custom database (like how wordpress works) and to add a admin section to allow admin/users to edit docs right in the browser (like how Github lets you add wiki pages, and to paste images into pages real easily). I know this is probably out of the scope of this project, however, I would like to see what other people thought of the idea.

Thanks in advance.

Allow Daux.io to function without Internet Connectivity

When trying to run Daux.io on localhost without internet connectivity, I noticed that the menubar wasn't functionally properly. Quick analysis shows me that this application depends on jQuery library loaded from public internet, via Google CDN.

While I generally do support having jQuery loaded from CDN providers for public viewing, I still wanted to be able to write documentation while traveling without Internet connectivity (e.g. airplane, train, etc.)...

Maybe you would like to consider conditional loading techniques that will attempt to use CDN first and then fallback to local script if needed. More details can be explained at this StackOverflow article.

Please let me know if you support this and wish me to create pull request for this minor suggestion.

redirection

I've downloaded the last version.
I put daux in "mydomain/daux".
http://mydomain/daux/index.php shows the introduction page.
But "view documentation" gives a Not found error : The requested URL /daux/Getting_Started was not found on this server.
Where is the problem ? Thanks

Only prints 1st page in Firefox/Safari

Prints fine in Chrome, but will only print first page in Mac Firefox/Safari (Windows untested).

landing page per folder?

is there a way for creating a landing page for every folder? thanks a lot

Add Option for keeping index.php in links

This would be a nice thing to have as some people don't have access to their servers config and not all support .htaccess files. The system currently works by placing index.php in the URL however links generated from the md files don't include this.

Plans for supporting Github-flavored markdown tables?

Are you planning to add support for Github-flavored markdown tables as defined here:

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#wiki-tables

Create a grunt task to build a static set of the docs.

This would be useful if you wanted to deploy to S3, Github Pages, or any static file server.

From reddit user:

This project looked very appealing to me, until I read this part. I am not interested in a service like DocumentUp, I just want to be able to put the generated documentation on our CDN or S3, on our domain. We also have the need for internal docs that we don't want on any public server.
I think the solution to this is to add support for optional, purely static export. An external, hosted documentation service will not fit our needs.

fontend bug

I don't sure this is a bug if you mean it's a feature or style

However,if it's really a bug.I hope the information I provided below will help:

link:http://daux.io/Getting_Started
browser:chrome Version 28.0.1500.63
system:ubuntu 12.04

No CSS applied after install

The documentation says, "Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP." Surely there must be more to it than that, as the application renders without any CSS applied to it. Tried on two different servers with PHP.

Code highlighting detecting this markdown as applescript

Hi, I have the following code block as a part of my markdown page and when the page renders the pre has the class applescript. This means, for instance, the #headings are being detected as comments, is is being detected as a keyword, etc.

## Hello World

This is a simple document. It has really cool **bold text** and *OMG ITALICS*. This is _bold_ too and this is __italic__.
Shiz gets real serious when you ***bold and italic words***.

### Code

Tawkin' 'bout `code that does things` and showing some code:

   <p>Here, the four space indent means, I'm showing some codez.</p>

### Lists

Here's a list, holy bejeebus!

* Buy milk
* Buy sausages
* Run down a hill, flailing arms wildly.

Here's some things to do in order:

1. Update Repo.
2. Fix Code.
3. Commit Fixes.

Any ideas?

Perhaps we could have a trigger for code that overrides the automatic detection?

JSON on PHP 4.x

Would it be possible to avoid using JSON for the config file? I'd like to use this for hosting some intranet documentation, but I only have access to a PHP 4.x server so json_decode is not available.

I've tried to look up some classes or libraries that backport JSON to PHP4, but nothing's worked so far (mainly because the JSON file has nested elements, and the application expects the JSON data as an associative array.

I'm not sure if there's anything else that would hold this app back from being able to work on 4.x, but if this is the only issue, the cause should be relatively easy to fix.

Keeping daux update without overwriting personal changes

What is the best way to keep my version of daux.io updated with the latest version from GitHub without git overwriting the changes I have make in the "docs" directory. When I do a git pull, git complains about wanting to overwrite my changes to the config.json file. Thanks.

CSS error on docs

Looking through Daux for the first time today, and saw the attached error when looking at http://daux.io/Examples/GitHub_Flavored_Markdown - Chrome, OSX, large monitor. The code and pre tags sit inside the blue on the right instead of in the main content. Happens at over 1150px wide, slightly clearer to see the problem on http://daux.io/Examples/Code_Highlighting.

.DS_Store file showing when running local

EDIT: Sorry - I had not seen this is a duplicate! I don't believe I can delete it myself, can I?

Not a huge deal, but is there a way to prevent the .DS_Store files from showing when running daux locally? (view picture)

Online demo not rendering correctly

Not sure if it's just me, but the online demo is not working as expected.
Using Chrome Latest Version 28.0.1500.72 m
http://daux.io/Examples/Code_Highlighting

Tablet and mobile works just fine.

This is my view.

Cannot display /docs, 404s being encountered

I've downloaded the repo and have been attempting to play with daux, and have been encountering 404s both locally and on a remote server when trying to access any of the example documentation.

I've scoured the documentation and I meet all of the requirements, so I'm wondering if I'm missing a particular dependency or other crucial element.

I've uploaded the master, completely un-edited, to http://www.example.com. The landing page works fine, as does editing 'config.json', but attempting to access any of the actual documentation results in a 404.

My webserver is hosted by MediaTemple, running PHP 5.3.26.

Thanks in advance for any help/suggestions.

Problems with special characters in a filename

Hi, great web app.

When I use spanish special characters in the filename (like ñ, á, é, í, ...), the app show the file and the characters correctly in the left panel. But when I click the file it dosn't open them.

Example:

• filename 00_Administración
• url http://localhost/Administración show:

Oh No. That page dosn't exist

Illegal characters in folder/markdown filenames

Is there currently a way to have the folders/files in /docs display with illegal characters? For example, you may want a file to display as What's New? in the app ... but naming the file What's_New?.md breaks things.

Can page title more friendly?

When we visit every web page generated by Daux.io,the title of web page is always the same.

Maybe we can get more friendly title for each page,for example:
use Getting Started--DAUX.IO not DAUX.IO for the page:http://daux.io/Getting_Started

And just a idea,is there a plan to make daux.io to support other language,such as Simplified Chinese and Japanese?

Thanks~☺

Falls apart on wide viewport

The Code Highlighting page falls apart on Firefox 22 ("Mozilla/5.0 (Windows NT 6.1; WOW64; rv:22.0) Gecko/20100101 Firefox/22.0"). It's good on 1145, and broken on 1150 (as given by document.documentElement.clientWidth).

Menu always expanded on mobile view

Tested on iPhone 4s, Samsung Galaxy S2, Google Nexus 7 and all mobile view menus are expanded by default.

Document edited timestamp feature

Any thoughts on adding a time stamp feature to the document pages for last time edited.

For this mockup I just added the following lines of code.

<div class="page-header">
<h1>Emails: Accepted Email</h1>
<span style="
    float: left;
    font-size: 10px;
    color: gray;
">Tuesday, July 23, 2013</span><span style="
    float: right;
    font-size: 10px;
    color: gray;
">9:34 AM</span>
</div>

Ignore files with filename starting with a dot (.htaccess, .DS_Store, etc.)

When running locally on a Mac, .DS_Store appears in Doc navigation. The problem should be the same with .htaccess files.
Maybe it should be good to exclude files starting with a dot from the navigation, in the get_tree function.

( Great work btw )

Major CSS issues

I'm getting very weird layout issues (and this all on daux.io). I think this is related to some serious b0rkage in the CSS. For me (on a decently-wide monitor) the whole layout is weird. I had a little play in the inspector, and various odd things happen because you're attributing styles directly onto Bootstrap's own containers, rows and spans.

What got me onto writing this issue is that the GFM page was useless for me (the GFM page is a great example but not the only broken page - they all do this as far as I can tell). At mobile widths it's fine, at small desktop and tablet widths it's okay (a few subtle oddities), but at desktop widths (looks to be related to the media query for min-width: 1150px) lists go weird and code areas show outside of the page area. Sceenshots:

Mobile (normal):

Tablet (normal):

Desktop (b0rk):

It looks like it may have something to do with floating. But there's plenty of other weird stuff going on here (the fork banner is one, the fact that some of the page content goes outside the scrollbar is another): (screenshot from tablet width)

The blue on the far right is the body background, somehow appearing outside the page content area, or is the scrollbar somehow coming inside the page? It also goes away when I make my browser a little bigger but still within the 'tablet' (or is it small desktop?) breakpoint. Anyway, this is obviously related to the bits overlaying the scrollbar referenced in issue #1

So I tried playing around with the CSS in the web inspector and found that, for instance, disabling the overflow: auto style from .content-area, .article-tree rule (compiled daux-navy.css line 6494) fixes some of this (and a lot more, see below), but then introduces other problems like the left-hand nav not scaling to the full browser height.

---

Basically I think you've customised Bootstrap too much. Applying extra styles to Bootstrap's own containers, rows and spans can certainly make things not work out quite right, and I think there's so much going on here it's hard to pin down exactly what's causing it (if it even is one thing).

Sorry this hasn't been a very optimistic bug report. Good luck!

CSS: Code blocks shifted to the right on wide windows?

Is it intended that code is shifted to the right?

(Google, Chrome, on Ubuntu, screen: 1680x1050)

URL doesn't show index page into a folder

When you have folders and into this folder contains index.md, then shows this index.md the first time, but when you write the URL in the browser's box didn't shows the index page

Code highlighting needs additional css styles

Reported by reddit user:

Source code formatting doesn't seem to work.

The code formatting is working, but there are not enough style differences in our custom themes to make the code highlighting more visible.

Source

What's your goal?

What's your goal of this project?

as I know Doxygen which is also a document generator can generate document base on the document in code source

And now what you have Done seems more like what wordpress do to bloger

Is it a handy template for document or a real document generator?

Adding a simple login system

Is their a way to add an optional simple login system to this documentation web app? I would love to use this for my company web app documentation, however, it has some sensitive information that I need to keep secure. Thanks for your suggestions.

Github spice urls and references are not auto linking

Reported by reddit user:

The "Github spice" and what I assume are supposed to be LaTeX formatting don't work in your example: http://cl.ly/image/1Q0Q0n2t0O0Q

Source

a website use daux.io

I use daux.io to build a website for one of my free softwares.

daux.io is easy to use,thanks!

The website link is:http://vdhelper.sinaapp.com/

spurious ordered list items

The following screenshot was taken from here while viewing in Chrome 27.0.1453.116 on OS X Lion.

I suspect that the circled items and NOT intended.

Small floats issue with page header

The page content floats into the header space at certain widths.

Referencing /js and /css will not work when daux is not in root of web directory.

If you use /js and /css then it will be trying to get the css and js from /var/www not the local directory of ex: /var/www/docs/

Plans for search?

Curious if search is in the future roadmap?

404 error

Hello. I have the same problem as ljvasey( #39) had. I checked the .htaccess file and other files had been uploaded completely, but I can't open documentations. I tried on remote server with PHP version 5.3 and 5.4 both.
I wonder if I miss something...

Add code substitution functionality

This is great project and I really love the simplicity of it, but there is one feature that would make this perfect. (I didn't see this in the documentation, so if it exists, disregard this).

It would be fantastic if we could reference an external script for a code block in the markdown and have it be automatically transposed into the documentation (Think erb template in Ruby, but with a path to the scrip). This would allow me to update a script apart from the markdown file, yet have the content in the documentation show this change without having to do any further work.

Currently, it appears that I would have to cut and paste a script or code block into the markdown file every time I update it. I think this would be a great addition to this project if possible.

Thanks for all the hard work you've put into this. I plan on using this daily.

Github featured banner is over top the scroll bar.

Source
Screenshot

This might be due to z-index.