pandocでドキュメント管理する話

1. 月刊LT 2014年12月号
webドキュメントを
楽に管理したい
--pandocを使って簡易CMS--
@m2wasabi
2014/12/12

2. 自己紹介
• 山本允葵
(Masaki Yamamoto)
o 株式会社バニーホップ
o 裏方エンジニア
o 特技：つまみ食い

3. おしながき
• Markdownについて
• Markdownの問題点
• pandoc
• 便利ツール作ってみた！

4. webのドキュメント管理
何使ってますか？
• Sphinx
• wiki( *wiki , GitHub , Backlog , etc..)
• CMS(wordpress など)
ドキュメントの記法は同じですか？

5. Markdown記法
• オンラインのドキュメントは
Markdown記法でなんでも書ける時代
o GitHub
o Qiita
o WordPress
o Backlog wiki

6. Markdown方言問題
• エディタやコンバータで文法が細かく異なる
o 標準Markdown
o PHP拡張
o GitHub拡張MarkDown
o Qiita拡張MarkDown
• デファクトスタンダード
o GitHub拡張MarkDown
• 対応しているエディタが多い
o SublimeText , Atom , Kobito , MarkdownPad , etc.

7. GitHub拡張MarkDownに一言
• 定義付きリストの書き方がダサい！
そのままとは…
HTMLタグ書きたくないし！
出典： Qiita - Markdown記法チートシーhttp://qiita.com/Qiita/items/c686397e4a0f4f11683d

8. その他問題点
• 可搬性低い
o webに公開する場合、フォームに入力、
コピペデプロイが主流か！？
o かろうじてKobitoなどでファイルとオンラインで残せるが、
Qiita専用。

9. ぼくのかんがえたさいきょうの
ドキュメント管理
• 可搬性がよくて
• 楽に書けて
• バージョン管理も使える
• 単純な仕組み
それを満たしてくれるツール
pandoc

10. pandoc
• コマンドベースのドキュメントコンバータ
• 変換できるフォーマットは・・・とても多いです
o HTML, XHTML, HTML5
o MarkdownText
o Tex, LaTex, ConTex
o PDF
o DOCX
o EPUB
o MediaWiki …他
• 中でも、MarkDownの変換機能が豪華
o Markdown標準, GitHub拡張, PHP拡張, pandoc拡張
o ベースのルールから文法を足したり引いたりできる
• 例) GitHub拡張に定義リストを加えたい⇒ markdown_github+definition_lists
• テンプレートを指定可能
公式サイト：http://johnmacfarlane.net/pandoc/
日本語ドキュメント：http://sky-y.github.io/site-pandoc-jp/users-guide/

11. 使い方
• コマンドラインで一発
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
• コマンド長い！！(#ノ゜д゜)ノ凸
そこで…

12. テンプレートキット
作りました
• テンプレートはとりあえずBootstrapに対応
• Markdownの書式はGitHub拡張+ 定義リスト
• バッチファイルでHTML 一発生成
https://github.com/m2wasabi/pandoc-authoring-template
短縮
http://goo.gl/mSpTe1

13. Demo
http://goo.gl/mSpTe1

14. 導入事例
• Zugyuuun!!
o 導入ページ
• リファレンス
• チュートリアル
o 管理方法
• 原稿管理用Gitリポジトリ
↓
バッチでhtml生成
↓
webサイト管理用Git
リポジトリにコミット
↓
内部Previewに自動デプロイ
↓
問題なければ本番デプロイ
https://www.zugyuuun.com/ http://goo.gl/mSpTe1

15. まとめ
• pandoc を使うとドキュメント変換充になれ
る！
o 余談：書籍化狙ってるならTexやEPUBもアリかも？
• 便利なテンプレートキット作りました！
o みんなで使ってください！
o テンプレートがしょぼいのでPullRequest待ってます(´・ω・｀)
o Company blog で記事書きました。
http://www.bunnyhop.jp/tips-20141208/
ありがとうございました！
http://goo.gl/mSpTe1
Next:
Gulpで自動デプロイ(楽にできそう)
require('gulp-pandoc');