記法のシンプルさ、機能そして素の状態でも可読性が高いと言ったこともあって人気のMarkdown。利用範囲がどんどん広がっています。READMEだけでなく、プロジェクトのドキュメントを書く際にも利用してみると良いでしょう。 そうなると単純に一つのMarkdownファイルだけでなく、複数のファイルで構成した分かりやすいドキュメント構成にしたくなるはずです。そこで使ってみたいのがParmです。 ParmはPython製のスクリプトで、parと組み合わせ使います。どちらもインストールはpipでできます。 まずはparのインストールから。

$ pip install par
Downloading/unpacking par
  Downloading par-0.9.5.tar.gz
  Running setup.py egg_info for package par
    
Installing collected packages: par
  Running setup.py install for par
    
Successfully installed par
Cleaning up...

続いてparm。

$ pip install parm
Downloading/unpacking parm
  Downloading parm-0.9.1.tar.gz (757kB): 757kB downloaded
  Running setup.py egg_info for package parm
    
Installing collected packages: parm
  Running setup.py install for parm
    
    Installing parm script to /usr/local/bin
Successfully installed parm
Cleaning up...

これで準備は完了です。まずプロジェクトフォルダを作成してparm initを実行します。

幾つかの質問に答えると必要なファイルが生成されます。

フォルダ構成です。

index.mdは最初の表示、その内容がintroduction.mdになります。実際の内容を記述するファイルは自由に増やせます。

index.mdの内容です。目次を出力しているだけですが、その内容もMarkdownファイルを指定しているだけです。

introduction.mdの内容。普通のMarkdownテキストです。

HTMLにする際にはparm makeを実行します。デフォルトではプロジェクトディレクトリ以下にHTMLが生成されますが、別途ディレクトリ指定も可能です（-dオプション）。

生成されたHTMLファイル。まさにソフトウェア向けと言った感じです。

目次を辿ったところ。左側にメニューも出ています。

Parmではテーマもサポートされており、BootstrapかSemanticが選択できるようになっています（デフォルトはSemanticです）。その他の機能としてreStructuredTextをサポートしていたり、GitHub Pagesとしての発信も考慮されています。 ツールとしてはシンプルでMarkdownベースでドキュメントを書いてそれをHTMLに変換する上で複数ファイルに分割できるのは便利ではないかと思います。社内の開発ドキュメントして使ってみても良さそうです。 ParmはPython製のオープンソース・ソフトウェア（BSD License）です。 Parm limodou/parm