Vivliostyle -MarkdownをPDFドキュメントに-

markdownドキュメントを扱っているが、お客様に提出する際にmarkdownでは問題と言われた際に提案するためのスライド

Transcript

1. CSS 組版で Markdown を提出物に Markdown を、そのまま お客様に出せる PDF へ ― 組版ツール「 Vivliostyle 」のすすめ ― Markdown で書きたい。でも提出は PDF 。その悩み、今日で終 わりです。 ▲ Vivliostyle で生成した実際の PDF
2. なぜドキュメントを Markdown で書くのか 理由① Git で管理できる 理由② 生成 AI が読み書きできる • Word / Excel はバージョン管理が破綻 しがち • Word / Excel は図形・結合セルで認識 精度が落ちる • GitHub 等で差分レビューができない • • テキストの Markdown なら差分・履歴 ・レビューが全部使える 読めてもトークン（≒お金）を無駄に消 費 • バイナリの「編集」は読むよりさらに困 難 Markdown はただのテキスト。だから Git でも生成 AI でも自在に扱える。
3. 具体例：追加仕様が来て、修正が必要になったら Excel で管理していた場合 Markdown ＋ AI の場合 ① 該当箇所を人手で全部探して修正 ① 人が AI に修正を指示 ② 修正箇所に目印 → レビュー → 目印を外す ② AI がドキュメント・コード・テストを修正 し、自動テスト後にプルリクエスト ③ そのあと実装・テスト・実装レビュー… 修正漏れや「実装だけして仕様書は放置」が 頻発 ③ 人は Git 上で差分をレビューしてマージ 人間の仕事は「方向性の決定」と「受け入 れ」だけ
4. ただし、 Markdown には弱点がある エンジニア同士なら エディタや GitHub でそのまま読める。何の 問題もない。 お客様への提出物としては Markdown を読める標準ソフトがない。求 められるのは、体裁の整った PDF 。 Markdown から “きれいな PDF” を自動生成できればいい それをやってくれるのが Vivliostyle
5. Vivliostyle とは？ ― CSS 組版ツール CSS 組版 Markdown / HTML の原稿を、 CSS のルールで「本 の見た目」にレイアウトする技術 書籍品質の PDF 出力 表紙・目次・ページ番号・脚注まで自動で組んで PDF に書き出す Markdown / HTML ↓ ＋ CSS （テーマ） ↓ オープンソース & CLI 無料で使える OSS 。コマンド 1 発でビルド、ライブ プレビューも可能 書籍レイアウトの PDF
6. 出力例① 表紙も目次も、自動で「本」になる 表紙 目次（見出しから自動生成） 原稿はぜんぶ Markdown 。目次もページ番号も手作業ゼロ。
7. 出力例② 表組み 表・コード・図も、そのままきれいに コードハイライト 開発ドキュメントに必要な表現は、ひと通りこのまま通る。 Mermaid 図
8. 使い方は、実質 2 コマンド 1 書く いつも通り Markdown で書くだけ → 2 ビルド CLI で PDF を生成 → 3 できあがり そのまま提出できる PDF $ npm install -g @vivliostyle/cli $ vivliostyle build spec.md -o spec.pdf # 書きながら確認するなら : vivliostyle preview spec.md 見た目を変えたいときはテーマ（ CSS ）を差し替えるだけ。公式テーマも多数。
9. チーム運用： CI/CD で PDF は勝手に最新になる Markdown を編集 → Git に push / プルリクエスト → CI が vivliostyle build を実行 → 最新 PDF が 自動で配布物に 人が触るのは Markdown だけ。提出用 PDF は常に最新が置いてある状 態に。
10. 補足： CSS 組版だから、「書籍」までつくれる 紙面設計は CSS で自由自在 判型・余白・柱・ノンブル（ページ番号）まで CSS で 指定できる 日本語組版に強い 縦書き・ルビなど、日本語の本に必要な組版に対応 本づくりの実績 技術同人誌から商業出版まで、実際に本の制作に使われ ている 同じ Markdown 原稿から 提出用 PDF 印刷入稿用 PDF 技術同人誌・書籍 テーマ CSS を差し替えるだけ
11. まとめ： Markdown で書いて、 Vivliostyle で出す 1 Markdown で書けば、 Git と生成 AI をフル活用できる 2 Vivliostyle が、そのまま提出できる品質の PDF に変えてくれる 3 CSS 組版だから、その先の「書籍化」まで視野に入る 今日から試すなら → npm install -g @vivliostyle/cli