joDoc uses markdown as its core to provide simple, human-readable docs which it converts to HTML.
Basically, anything that ends up in an
<h1> tag becomes a keyword that:
- appears in the keyword index
- is turned into a link wherever it is used in your documentation text
- resolves in the TOC into links
Injecting HTML Snippets
Markdown supports inline HTML, so your code comments and markdown files may have arbitrary bits of HTML in them.
joDoc also supports HTML files, so you can use it to bring together docs built from other tools. The autolink feature works at the HTML level, so by just including HTML files in your doc project, they become linkable from other document pages automatically.
vs. Natural Docs
For those who want more insight into how the documentation is created:
for each markdown file in your project, convert to an HTML file for each source file, produce a markdown file from all text between `/**` and `*/` comments convert the markdown file into an HTML file for each HTML file, for each `h1` tag, add an `id` field based on the contents of the `h1` tag add contents to a `file.html#id` keyword index for each HTML file, for each keyword in our index, intelligently wrap the keyword with an `a` tag that points to the `file.html#id` from our keyword index produce an index: sort the keyword index save the keyword index as an HTML file save the keyword index as a JSON file produce a table of contents: build sections based on directory names retain sorted directory order save as a JSON file save as a formatted HTML file concat all html files into one document: structure: header table of contents contents from all html files, in order sorted keyword index footer convert all fixed paths to local references: (e.g. `filename.html#about` becomes simply `#about`)
This produces a bundle of files which can be used a couple of ways:
A loose set of files which is used by the joDoc application (written using the jo library, of course)
An alternative "single page" view of all the documentation (which some people really like)
Your own collection of files with some other organization means (which is trivial to do with pre-rendered HTML and the JSON document structure).