Mizuho documentation formatting tool
Mizuho is a documentation formatting tool, best suited for small to medium-sized documentation. One writes documentation in plain text files, which Mizuho then converts to nicely formatted HTML.
Mizuho wraps Asciidoc, the text formatting tool used by e.g. Git and Phusion Passenger for its manuals. Mizuho adds the following functionality on top of Asciidoc:
- A top bar that gives quick access to the table of contents.
- Commenting via Juvia.
Mizuho bundles Asciidoc so you don't have to install it yourself. Mizuho should Just Work(tm) out-of-the-box. Asciidoc uses GNU source-highlight for highlighting source code. GNU source-highlight depends on Boost and so is notorious for being difficult to install on systems without a decent package manager (e.g. OS X). Mizuho comes prebundled with an OS X binary for GNU source-highlight so that you don't have to worry about that.
- Nokogiri (
gem install nokogiri)
- Python (because Asciidoc is written in Python)
- GNU Source-highlight, if you want syntax highlighting support. If you're on OS X then it's not necessary to install this yourself; we've bundled a precompiled source-highlight binary for OS X for your convenience.
Run the following command as root:
gem install mizuho
You can verify the authenticity of the gem by following The Complete Guide to Verifying Gems with rubygems-openpgp.
First, read the Asciidoc manual to learn the input file format:
Next, write an input file and save it in a .txt file.
Finally, convert the .txt file to a single HTML file with Mizuho, with the default template:
This will generate 'input.html'.
Commenting via Juvia
To enable commenting via Juvia, pass
-c juvia and the
--juvia-site-key arguments with appropriate values. Mizuho will generate a
so-called ID map file if there isn't already one. This file maps section
titles to Juvia topic IDs. This way you can preserve a section's comments
even when you rename that section's title. Note that the section's number is
considered part of the title, so renaming can happen implicitly.
When a section title has been renamed, Mizuho will look for a Juvia topic ID
for which the previous title is similar to the new title, and assign that ID
to the section. The entry in the ID map file is then marked 'fuzzy' in order to
warn you about this. You have to remove the
# fuzzy comment in the ID map
file, or Mizuho will keep complaining about this in subsequent runs.
This tool is named after Kazami Mizuho from the 2003 anime 'Onegai Teacher'.