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.
Requirements
- 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.
Installation with RubyGems
Run:
gem install mizuho
This gem is signed using PGP with the Phusion Software Signing key. That key in turn is signed by the rubygems-openpgp Certificate Authority.
You can verify the authenticity of the gem by following The Complete Guide to Verifying Gems with rubygems-openpgp.
Installation on Ubuntu
Use our PPA:
sudo add-apt-repository ppa:phusion.nl/misc
sudo apt-get update
sudo apt-get install mizuho
Installation on Debian
Our Ubuntu Lucid packages are compatible with Debian 6.
sudo sh -c 'echo deb http://ppa.launchpad.net/phusion.nl/misc/ubuntu lucid main > /etc/apt/sources.list.d/phusion-misc.list'
sudo sh -c 'echo deb-src http://ppa.launchpad.net/phusion.nl/misc/ubuntu lucid main >> /etc/apt/sources.list.d/phusion-misc.list'
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 2AC745A50A212A8C
sudo apt-get update
sudo apt-get install mizuho
Installation on RHEL, CentOS and Amazon Linux
-
Enable EPEL: RHEL, CentOS, Amazon Linux.
-
Enable our YUM repository:
# RHEL 6, CentOS 6 curl -L https://oss-binaries.phusionpassenger.com/yumgems/phusion-misc/el.repo | \ sudo tee /etc/yum.repos.d/phusion-misc.repo # Amazon Linux curl -L https://oss-binaries.phusionpassenger.com/yumgems/phusion-misc/amazon.repo | \ sudo tee /etc/yum.repos.d/phusion-misc.repo
-
Install our package:
sudo yum install rubygem-mizuho
Usage
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:
mizuho input.txt
This will generate 'input.html'.
Commenting via Juvia
To enable commenting via Juvia, pass -c juvia
and the --juvia-url
and
--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.
Credits
This tool is named after Kazami Mizuho from the 2003 anime 'Onegai Teacher'.