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

1. Enable EPEL: RHEL, CentOS, Amazon Linux.

2. 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
   

3. 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'.