Changes introduced by the fork
- use a non Github-Flavored-Markdown, specifically https://github.com/coreyti/showdown .
mdoc - a simple markdown based documentation generator
This is a simple markdown based documentation generator, it will search all the markdown files inside the "input" directory and output an HTML file for each document, it will also generate a "TOC" (table of contents) for each file and links to all the pages on the index page, it also provides a basic search feature and quick browsing between classes/methods/properties.
Reasoning behind it: inline documentation, why I'm ditching it.
mdoc uses the github "codeblock syntax" to highlight code. E.g.:
Currently the parser considers H2 as sections/methods/properties names and will add them to the TOC at the top of each file and automatically generate deep-links to them. It's important to notice that mdoc only recognizes headers on the atx-style as a new section.
The first paragraph after the H2 will be used as description on the sidebar. Currently the search feature only searches copy from the title and description.
For a markdown syntax reference check: http://daringfireball.net/projects/markdown/dingus And also check the structure of the example files.
You can install it through NPM:
npm install -g mdoc
Command line interface
mdoc -i examples/basic/content -o examples/basic/out
For a list of available commands run:
Check files inside the "examples" folder. Run:
cd examples/basic node build.js
Check output inside "examples/basic/doc".
Check "examples/advanced" for all the available settings.
There are lots of things to improve, check the issues page for a list of bugs and feature requests.
I probably won't have free time to work on it till next year, any help is welcome. (it also keeps me more motivated)
Released under the MIT license.
- only uses descriptions if next block after header is a paragraph (#10)
- improve the way code blocks are converted (#11)
- fix page titles (#12)
- rename template files to "*.hbs"
- allow setting heading level that should be used for TOC and deep links.
- add option to set
assetsPathwithout needing to copy template files.
- add setting for default brush to Syntax highlighter at the top of asset JS file since some code blocks may not contain metadata.
- add nodejs api to examples.
- fix syntax highlighter.
- Command line interface.
- Add support for custom templates.
- Generate TOC and deep-links automatically.
- Switched most settings to optional.
- Fix links and paths to assets on nested folders.
- initial release.