webドキュメントを楽に管理したい

--pandocを使って簡易CMS--

月刊LT 2014年12月号

@m2wasabi

2014/12/12

自己紹介• 山本允葵

(Masaki Yamamoto)o 株式会社バニーホップ

o 裏方エンジニア

o 特技：つまみ食い

おしながき• Markdownについて

• Markdownの問題点

• pandoc

• 便利ツール作ってみた！

webのドキュメント管理何使ってますか？

• Sphinx

• wiki( *wiki , GitHub , Backlog , etc..)

• CMS(wordpressなど)

ドキュメントの記法は同じですか？

Markdown記法• オンラインのドキュメントは

Markdown記法でなんでも書ける時代o GitHub

o Qiita

o WordPress

o Backlog wiki

Markdown方言問題• エディタやコンバータで文法が細かく異なる

o 標準Markdown

o PHP拡張

o GitHub拡張MarkDown

o Qiita拡張MarkDown

• デファクトスタンダードo GitHub拡張MarkDown

• 対応しているエディタが多い

o SublimeText , Atom , Kobito , MarkdownPad , etc.

GitHub拡張MarkDownに一言• 定義付きリストの書き方がダサい！

http://qiita.com/Qiita/items/c686397e4a0f4f11683d

出典： Qiita - Markdown記法チートシート

HTMLそのままとは…

タグ書きたくないし！

その他問題点• 可搬性低い

o webに公開する場合、フォームに入力、コピペデプロイが主流か！？

o かろうじてKobitoなどでファイルとオンラインで残せるが、Qiita専用。

ぼくのかんがえたさいきょうの

ドキュメント管理

• 可搬性がよくて

• 楽に書けて

• バージョン管理も使える

• 単純な仕組み

それを満たしてくれるツール

pandoc

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/

使い方• コマンドラインで一発

• コマンド長い！！(#ノ゜д゜)ノ 凸

そこで…

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

テンプレートキット作りました

• テンプレートはとりあえずBootstrapに対応

• Markdownの書式はGitHub拡張 + 定義リスト

• バッチファイルでHTML 一発生成

https://github.com/m2wasabi/pandoc-authoring-template

http://goo.gl/mSpTe1

短縮

Demo

http://goo.gl/mSpTe1

導入事例• Zugyuuun!!

o 導入ページ

• リファレンス

• チュートリアル

o 管理方法

• 原稿管理用Gitリポジトリ↓

バッチでhtml生成↓

webサイト管理用Git

リポジトリにコミット↓

内部Previewに自動デプロイ↓

問題なければ本番デプロイ

https://www.zugyuuun.com/http://goo.gl/mSpTe1

まとめ• pandocを使うとドキュメント変換充になれる！o 余談：書籍化狙ってるならTexやEPUBもアリかも？

• 便利なテンプレートキット作りました！o みんなで使ってください！

o テンプレートがしょぼいのでPullRequest待ってます (´・ω・｀)

o Company blog で記事書きました。

ありがとうございました！

http://goo.gl/mSpTe1

http://www.bunnyhop.jp/tips-20141208/

Next:Gulpで自動デプロイ(楽にできそう)require('gulp-pandoc');