Zenn
📝

Vivliostyleで今度こそはじめる「Markdownで技術同人誌」（前編）

2020/12/01に公開
Markdown
Vivliostyle
vfm
tech

2020年末、技術同人誌をはじめて書くならVivliostyleで決まり！

（ってそろそろ言いたい……）

技術書典に代表されるように、技術同人誌[1]が盛り上がりをみせています[2]。

私は以前に「技術同人誌をMarkdownで書く」とは、実際どういうことか？という記事を書いたことがあります。書いた時期は2018年末でした。当時は「初心者が原稿をMarkdownで書いてPDFとしてビルドし、比較的安全に印刷所へ入稿する方法」が確立されていなかったと記憶しています。

その時期から状況は変わり、初心者に勧められそうな「技術同人誌をMarkdownで書く」ためのツールが登場しました。それがVivliostyleのCreate Bookです。

Create Bookによって、次の同人誌の制作・入稿ワークフローが比較的手軽に実現できるようになりました。

  • プロジェクトの作成
  • Markdownによる本文執筆
  • リアルタイムプレビュー
  • 同人向け印刷所に入稿するための本文PDFを生成する
    • press-ready の機能
    • PDF/X-1a仕様の“無難”な入稿用PDFに変換（絶対に安全というわけではありません）

これから3回（予定）で、主にCreate Bookを用いた技術同人誌の作成方法を紹介します。
このシリーズでは細かい点（CSSのカスタマイズなど）には極力触れず、本文PDFをつくる過程を追っていきます。

※以下は予定のため変更の可能性があります。
※中編が膨れ上がってしまったので、2つに分割しています。

Vivliostyleとは

VivliostyleはCSS組版というWeb標準技術をベースにした、自動組版システムのオープンソースプロジェクトです。

CSS組版はHTMLとCSSをベースにしています。本をつくるための選択肢はいくつかありますが、普段からHTML/CSSを扱っている人にとってはVivliostyleのプロダクトが比較的手軽に感じるでしょう。

開発は活発に行われており、Vivliostyleユーザー会では「開発者とユーザーの集い」や合同誌頒布が定期的に行われています。

和文組版の観点でVivliostyle（vivliostyle.js）をみると、商用実績のある他の組版システム（LaTeX・InDesignなど）と比べて未熟であることは否めません。しかし商用のCSS組版システム（VersaTypeシリーズやAH Formatterなど）は実際に販売・運用されていることから、原理的に「CSS組版だから品質が悪い」なんてことはないでしょう[3]。エコシステムの活況ぶりから、Vivliostyleの組版品質についても改善が急ピッチで行われると筆者は考えています。

入門や実践的な内容は、公式チュートリアルガイドやVivliostyleユーザー会の合同誌「Vivliostyleで本を作ろう」のシリーズがわかりやすくお勧めです。Create BookについてはVol.4に掲載されています。

（12/26から開催される技術書典 10にサークル参加する方など、急ぎで試したい方はぜひ下記を！）

Vivliostyle Flavored Markdown（VFM）

Create BookがサポートするMarkdown方言は、Vivliostyle Flavored Markdown（VFM）です。

VFMは「本の執筆に最適化したMarkdown」の標準化を担うべく、策定中（working draft）のMarkdown方言です。2020/7/2時点で1.0.0-alpha.10がpre-releaseされています。

目的や背景としては次があるようです。

実質標準である GFM も CommonMark を基に拡張されるのだから、実用面、規格面ともにこれを採用すればめでたしめでたし。GFM は HTML 埋め込みをサポートしているので、記法が物足りないならこれで補えばよい。

しかし文章、それも言語固有のものや書籍として必要な頻出要素 (ルビや脚注など) について HTML 埋め込みだけで対応するのは難しい。そのため Vivliostyle Project ではあえて新たな方言を定義することにした。それが VFM (Vivliostyle Flavored Markdown) である。

（中略）

VFM は Markdown という簡易マークアップ言語を採用することで文章と CSS 組版に集中するための方法として期待している。これまで CSS 組版と Vivliostyle には関心があっても、文章のために HTML を書くのは厳しいと感じていた人への訴求力がある。

Vivliostyle Flavored Markdown について

ユーザ向けのメリットとしては「既にMarkdownで書いている人にとって、覚えるべき記法が少ない」「本の執筆に最低限必要な記法が（順次）追加される」という点です。

記法は標準的な markdown であるGFM (GitHub Flavored Markdown) を、書籍向けに拡張した VFM (Vivliostyle Flavored Markdown) です。

GFM の上位互換ですから、慣れた人なら基本的な記法は GFM がそのまま使え、新たに覚えるのは VFM だけですみます。

Create Book - Vivliostyle Docs

（注：この記事は一般ユーザに向けた記事なので、「本当に上位互換かどうか」はMarkdownソムリエ各位に委ねます）

まだ段階としてはpre-release（かつworking draft）なので、出力の安定性を議論できる段階ではありません。それでも「これから本を書いてみたい」というライトユーザーにとっては、有力なMarkdown方言だと思われます。

で、VFMってどんなの？

前置きが長くなりましたが、VFMのサンプルをご紹介します。

---
title: チベット旅行記
---

# 第三回　探検の門出及び行路

（中略）

## 航海の快楽

郷里の親友信者が波間のボート中より各自に帽子あるいはハンカチーフを空に振りつつ壮快に西に向って進行するわが舟を見送りましたが、その後は和田の岬より古き{親近|なじみ}の金剛{信貴|しき}{生駒|いこま}の諸山に別れてただ我が一心を主として行くこととなりました。{門司|もじ}を過ぎ玄界灘より東シナ海を経てホンコンに着くまでは船長及び船員らと親しくなって時々法話を致しました。ホンコンでタムソン<span class="footnote">編者注：ディビッド・タムソン（David Thompson、1835-1915）だろうか？</span>という英人が乗船した。彼は日本に十八年間も居ったと言うのでなかなか日本語をよく使う。彼は非常な{耶蘇|ヤソ}教[^1]の熱心家で私と大変な議論が始まって船中の評判になった。なかなか愉快の事でありました。特に船員らは法話を非常に喜んで聞きましたから私も喜んで一つの歌がでました。

> 御仏のみくににむかふ舟のうへのり得る人の喜べるかな

![神戸港頭の袂別](img/fig49966_01.png){width="351" height="509"}

[^1]: 編者注：キリスト教。Jesusの中国音訳語「耶蘇」の音読みから。

ビルド結果1

ビルド結果2

なにやら読みがなを打っているような記法 {親近|なじみ} がありますね。VFMの最大の特徴はルビ記法です。{親文字|ヨミ}のように書けば、ルビが打てます。

いくつか補足します。まず、VFMの改行はGFMと同様に強制改行（hard line break）です。つまりMarkdown原稿上の改行1つ（Enterキー）がそのままPDF出力の改行（<br>）として反映されます。上記サンプルで主となる段落が異様に横長となっているのは、適当なところで改行すると出力上でも（意図せず）改行されてしまうからです。Markdown原稿上で改行（Enterキー）を2回打てば、通常の段落（<p>）ができます。

次に、（広義の）VFMにおける「注」は2つあります。

  • 後注（こうちゅう）：各章の後部にまとめて述べる注記
    • Create Book VFMの実装では利用可能[4]（※2020-12-12修正）
    • 例：[^1]（後注参照）、[^1]: foo（後注本体）
  • 脚注：本文（ページ）の下につける注記
    • VFMの標準的な記法ではない
    • テーマパッケージ @vivliostyle/theme-techbook の記法（すなわち上記サンプルはtheme-techbook向けです）
    • 例：<span class="footnote">foo</span>

最後に、VFMではGFMでお馴染みの表やインラインコード・コードブロックも利用できます。さらにVFMではコードブロックにキャプションを入れられます（app.jsの部分がタイトルです）。

```javascript
function main() {}
```

```javascript:app.js
function main() {}
```

```javascript title=app.js
function main() {}
```

まとめ

CSS組版のOSSプロジェクトVivliostyleを紹介しました。
またVivliostyleエコシステムの上で簡単に本を作れるCreate Bookと、Markdown方言のVFMについて軽く触れました。

次回はCreate Bookのインストールと、より具体的なサンプルでのビルドを体験してみましょう。またVFMの記法もいくつか紹介します。

脚注

  1. 同人誌（＝自らの資金で書籍を作り頒布する書籍）、のうち技術に関する内容を主とするもの。 ↩︎

  2. 初めての「技術同人誌」作り　「技書博」に出て記者が得たもの (1/3) - ITmedia NEWS ↩︎

  3. CSS組版の得意・不得意はあるようです。アンテナハウス株式会社のAH Formatterの説明には「マニュアルのような複雑なレイアウトには XSL-FO が、比較的単純なレイアウトには直感的な CSS がお薦めです」と明記されています。 ↩︎

  4. 補足（2020-12-12）：VFMの仕様では、標準的な記法ではありません。vivliostyle/vfm: revive-parse.tsでremark-footnotesが記述されています。 ↩︎

Discussion