over 4 years ago

markdownは簡易的なドキュメント作成には最適で、近年はgithubやQiita等の一部のWebサービスでは標準で使用できるドキュメントフォーマットとして定着しつつある。htmlと同様にあらゆるテキストエディタで編集可能ではあるが、ライブプレビュー機能を持った専用のエディタもあり、以前より利用しやすくするための環境が整いつつある。

markdownは仕様として、見出し、段落、表、箇条書き、図を扱えるだけだが、一部のプラットフォームでは目次(TOC)を扱えるようにしたり、数式をサポートする等+αな形態でmarkdownを利用することも可能。

また、markdown自体には見栄えに関する扱いは無いが、markdownが主にhtmlに変換され利用されるため、結果的にCSSで見栄えのよいドキュメントを作成することができる。

markdownで見栄えのよい仕様書/設計書を作成する

markdown+αで見栄えのよい仕様書/設計書を作成することができる。+αで利用するコンポーネントは以下の通りである。

pandocはスイスナイフ的に便利なドキュメントコンバータで、markdown以外に,pdf,html,docx,epub等無数のフォーマットに対応し、相互に変換できるとしている。一部のフォーマットについては外部のコンポーネントに依存しており、単体で全てのフォーマットに対応できているわけではないようだ。

wkhtmltopdfはhtmlからpdf,psフォーマットへ変換するコンバータ。pandocでは、pdfへの変換は外部のコンポーネントを追加しなければならないが、その代用としてwkhtmltopdfを使用する。

pandocもwkhtmltopdfも環境変数PATHに追加しておく、追加したら

pandoc target.md -c target.css -o target.htm
wkhtmltopdf -b -t --toc-header-text "目次" --cover cover.htm target.htm target.pdf

で、最終的にtarget.pdfを生成することができる。

pandocの-cオプションはCSSを設定する-oは変換先のファイル。

wkhtmltopdfの-bは書籍のような見た目ににする。-tはtocをつける。--toc-header-textはtocのラベル。--coverは引数のhtmlを表紙にする。target.htmは変換元のhtmlで、このhtmlは複数設定できる。なので、章毎にhtmlを分けて結合するという運用も可能になる。

基本的にwkhtmltopdfは変換元のhtml+cssの見栄えをそのまま生かした形でpdfへ変換してくれるが、cssの書き方によってはうまく画像を表示しない等見栄えに差がでる場合があるので注意する。

← ERMaster Sublime Text →