PICK UP

ドキュメント作成が捗る!!Pandocを利用した事例のご紹介(便利なオーサリングキット付き!)

TIPS

山本 允葵

ドキュメント、マニュアル作成というと、その作業量、メンテナンス性に圧倒され、開発者でなくとも眉をひそめる作業だと思います。
最近は、 MarkdownText というイージーなドキュメント書式がOSS界隈で流行ってますが、
Markdown書式を少し拡張しつつhtml化したときに任意のテンプレートを適用することが出来れば、記事作成も捗ります。

今回は、見た目と可搬性の両立をするためにドキュメント変換ツール pandoc を用いて
その問題を解決してみました。

以下だらだらと説明が続きますが、さっさと使わせろ!という方は、記事一番下のGitHubリンクをお試しください。

pandoc でhtmlを生成するチュートリアル

まずはpandocをインストール

以下ページから各OS用のバイナリがダウンロードできます。 http://johnmacfarlane.net/pandoc/installing.html

テンプレートファイルを編集する

※下記内容の詳細や、より深い内容は、日本語版ドキュメントを参照してください。
Pandoc ユーザーズガイド 日本語版

http://sky-y.github.io/site-pandoc-jp/users-guide/

html化する場合、出力結果をテンプレートファイルにあわせて編集することが出来ます。
まずは、デフォルトのテンプレートを取得しましょう。
今回の場合、html5で出力したいので、以下のようにコマンドを入力します。

pandoc -D html5 > template.html

これで、 template.html というファイル名でhtml5形式のデフォルトテンプレートが取得できます。
このファイルから、お好みにあわせて更新していきましょう。

html変換に使うコマンドを作成する

Markdown

最初に、変換元のMarkdownTextを作成します。

  • Windows の場合

echo # Hello world! > hoge.md

  • MAC/Linux の場合

echo '# Hello world!' > hoge.md

次に、htmlファイルの生成に使うコマンドを作成します。
各オプションを決めて、試しに適当なファイルを変換して、変換成功すれば大丈夫です

  • 出力させるファイルのフォーマットは -t FORMAT オプションで指定します。
  • MarkdownText から 他の形式への変換アルゴリズムは、細かく指定できます。
    大きく markdown , markdown_strict , markdown_phpextra , markdown_github の4種類で定義され、
    さらに+-で個別ルールの追加・削除が可能です。
    例) -f markdown_github+definition_lists
    GitHub拡張Markdown に定義リストのルールを付与する
  • テンプレートは、 --template=TEMPLATE_FILE のように指定します。
  • 読み込むCSSは、生成コマンドにおいて -c PATH を列挙することにより、複数指定可能です。
  • 章ごとのIndexを作成したい場合は、 --toc --toc-depth=n のオプションを追加します。
  • 完全なhtmlで出力したい場合は、 -s のオプションを追加します。

例では、オプションを以下のように指定してみます。

pandoc hoge.md -t html5 -f markdown_github+definition_lists --template=template.html -c css/a.css -c css/b.css -c css/c.css --toc --toc-depth=4 -s -o hoge.html

うまく変換できれば大丈夫です。

pandoc変換01

Markdownファイルを編集する

いつものようMarkdownファイルを編集しましょう。
ただ、ルール拡張した場合は、Markdownプレビューに対応したエディタで正常にプレビューできない場合があります。
しかし、所詮エディタのプレビューも地方ルール満載で、すべてのエディタで正常にプレビューできるMarkdownTextを書くのは不可能なので、
そこは気合いと慣れで乗り切りましょう。大した問題では無いです。
※GitHub拡張とかその先のQiita拡張とかも地方ルールです。でも便利だから使ってます

htmlに変換

先ほど用いた変換コマンドを使って変換ましょう。

より便利に運用するために ~pandoc用 htmlオーサリングキット~

記事の作成に必要なテンプレートを、bootstrapに対応し、
ワーキングディレクトリを分けたものを GitHub に公開しました。

使い方は以下です。

windows

  1. src\以下に *.md ファイルを作成し、編集する。
  2. make.bat を実行します。
  3. html\*.html が出来ている!

MAC OSX

  1. src/以下に *.md ファイルを作成し、編集する。
  2. make.command を実行します。
  3. html/*.html が出来ている!

cssは好みに合わせて追加・編集してください。
デフォルトページをそのまま表示すると、以下のように変換されます。

pandoc変換2

以上です。

12月15日(月)追記:LT資料アップ

12月12日(金)に開催された「年末特別号: 月刊ライトニングトーク2014年12月号」にてドキュメント管理に関するLTをしました。当日に説明で使用した資料をこちらでもアップします。記事とあわせてご参照ください!