Vivliostyle CLI による 合同誌作り @akabekobeko Vivliostyle User/Dev Meetup 2020 Spring 2020/4/4 1

もくじ 本⽇のテーマ Vivliostyle CLI Markdown SCSS (Sass) 要素技術を組み合わせる 共同執筆 VFM と Vivliostyle Pub 2

本⽇のテーマ 3

本⽇のテーマ 技術書典 7 で頒布した「Vivliostyleで本を作ろう Vol.2」の執筆環境について解説します 技術書典 応援祭で頒布中の Vol.3 も同系の環境です ソースコードは以下に公開されています Vol.1 https://github.com/spring-raining/tbf06-draft Vol.2 https://github.com/spring-raining/tbf07-draft Vol.3 https://github.com/spring-raining/tbf08-draft env-create-book https://github.com/akabekobeko/env-create-book Vol.1 を参考にして env-create-book を実装、それが更に Vol.2 以降の元となっています。 本⽇のテーマ 4

Vivliostyle CLI Vivliostyle CLI 5

Vivliostyle CLI とは？ Web 標準技術による組版エンジン Vivliostyle を操作するためのツールです 緑⾖はるさめさん (@spring_raining) により開発された vivliostyle-savepdf が元になっ ています 以下で絶賛開発中！ https://github.com/vivliostyle/vivliostyle-cli Vivliostyle CLI 6

できること Vivliostyle を利⽤して以下の機能を提供します。 Web 標準技術で記述された⽂書を組版して Web ブラウザーに表⽰する Web 標準技術で記述された⽂書を組版して PDF 出⼒する これらを簡単なコマンドで実⾏する Web 標準技術とは主に HTML/CSS となります。Vivliostyle 本体でもこれらは可能ですが、 動かすまでの環境を構築するのは⼿間です。 Vivliostyle CLI をインストールすれば、あとは HTML/CSS を⽤意するだけで Vivliostyle に よる組版機能を簡単に利⽤できます。 Vivliostyle CLI 7

インストール Vivliostyle CLI は npm として配布されています。Node.js と npm が利⽤できる環境を整え たら以下のコマンドを実⾏することでインストールされます。 npm install -g @vivliostyle/cli Vivliostyle CLI 8

使い⽅ HTML/CSS で記述された⽂書が content に配置されているならば、以下のコマンドで組版 されたものを Web ブラザーへ表⽰します。 vivliostyle preview content --book PDF 出⼒の場合は以下のコマンドになります。 vivliostyle build --book -s JIS-B5 content HTML/CSS の書き⽅は「Vivliostyleで本を作ろう Vol.1」内の記事が参考になります。 Vivliostyle Viewer で CSS 組版ちょっと⼊⾨ - 村上 真雄 @MurakamiShinyu https://vivliostyle.github.io/vivliostyle_doc/ja/vivliostyle-user-group- vol1/shinyu/index.html Vivliostyle CLI 9

課題 Vivliostyle CLI は⾮常に便利ですが、組版される HTML の記述には課題があります。 ⻑い⽂章を素の HTML で書くのは厳しい タグ記法の冗⻑さによるタイピング増加 タグ整合を取りながら書くにはツールの補完が必要 実例として著名な CMS ツール WordPress も基本は HTML で記述しますが、段落となる

の省略を許可したり WYSIWYG エディターを提供しています。 こうした補助なしに、⻑い HTML を破綻なく快適に書くのは難しいのです。 Vivliostyle CLI 10

Markdown Markdown 11

簡易 HTML としての Markdown ⾒出しや段落など、⽂章に頻出するものを簡易に書ける記法として Markdown が普及してい ます。 # Title The quick brown fox jumps over the lazy dog このような簡易記法で⽂章を書けます。また処理系によっては Markdown の記法で⾜らない 機能を HTML 埋め込みで補うことも可能です。 合同誌の執筆環境ではこの点を評価して、Markdown (with HTML) な記法を採⽤しました。 Markdown 12

Markdown を HTML に変換する ⽂章を Markdown で書き、組版を担当する Vivliostyle CLI には HTML として渡します。そ のための変換ツールとして remark を選びました。 remarkjs/remark https://github.com/remarkjs/remark remark とその周辺ツールを利⽤することで、Markdown を好みの HTML に変換できます。 プログラミングの知識は必要となりますが、代わりに独⾃の処理も追加できます。 合同誌の場合、Markdown 冒頭に著者などのメタデータを記述できるようにして、それを HTML 要素の CSS クラス名へ反映させるなどの独⾃処理を実装しました。 Markdown 13

校正 ⽂章の校正は textlint を利⽤。これは様々なルールを組み合わせて校正するためのツールで Markdown にも対応しています。 textlint/textlint https://github.com/textlint/textlint ルールの npm をインストールして .textlintrc というファイルに設定を定義。以下のよ うにコマンドを実⾏することでルール違反している箇所を教えてくれます。 textlint ./src/content/** ルールとして「全⾓・半⾓の分かち書き」などを⼊れています。合同執筆ということもあっ て利⽤は強制しませんでした。実際に採⽤したのは私だけかもしれません。 Markdown 14

VS Code (Visual Studio Code) 私は執筆⽤のテキスト エディターに VS Code を採⽤しました。理由は以下となります。 標準で Markdown 対応、リアルタイム プレビューもある textlint プラグインによってリアルタイムに校正できる 難点として macOS 環境かつ Google ⽇本語⼊⼒だと変換候補のポップアップ位置がズレる 問題があります。 当該 Issue https://github.com/microsoft/vscode/issues/45629 執筆当時はこれを我慢して (慣らされて) 使⽤していたのですが、最近のバージョンだと完治 はしていませんが症状は改善されてきたようです。 Markdown 15

SCSS (Sass) SCSS (Sass) 16

SCSS (Sass) Vivliostyle CLI による組版で HTML と共に重要なのが CSS です。これは外観を担当しま す。⽂章と異なり CSS は外観の定義なので、素の CSS で書いても実⽤⼗分です。 しかし CSS ファイルの分割と参照、クラス階層化などの便利な機能を利⽤したいので Sass を採⽤しました。記法は CSS 標準に近い SCSS です。 Sass: Syntactically Awesome Style Sheets https://sass-lang.com/ Sass: Syntax https://sass-lang.com/documentation/syntax#scss SCSS で書いたものをツールで CSS に変換しています。これを HTML と同じく Vivliostyle CLI が参照する位置へ出⼒することで、組版対象となります。 SCSS (Sass) 17

SCSS のファイル分割 CSS 標準でもファイルを分割して @import により参照できます。しかしこれは HTML に読 み込まれた際に参照を解決してゆくため、HTML の解析処理をそこで停⽌させてしまいま す。 SCSS の場合は CSS 変換時に参照を解決し、その結果を単⼀ CSS ファイルに出⼒できま す。そのため開発側の都合で気軽に分割しています。 今回は利⽤しなかったのですが、この性質を利⽤して 合同誌の執筆者ページ単位で SCSS ファイルを⽤意して出⼒をカスタマイズする という構想もありました。 SCSS (Sass) 18

要素技術を組み合わせる 要素技術を組み合わせる 19

タスク ランナー 要素技術は揃いましたが、これらを個別に実⾏するのは⾯倒です。そこで組み合わせるため の仕組みを利⽤します。これをタスク ランナーと呼びます。代表的なものは以下。 Grunt https://gruntjs.com/ Gulp https://gulpjs.com/ npm-scripts https://docs.npmjs.com/misc/scripts Grunt、Gulp の順に流⾏。私も利⽤していました。しかし 2016 年からは npm-scripts に落 ち着いています。 拙ブログの解説記事 https://akabeko.me/blog/2016/10/npm-scripts-web-front-end- development/ 要素技術を組み合わせる 20

npm-scripts 1 npm-scripts は npm の機能です。Vivliostyle CLI をインストールできている環境なら有効に なっています。Node.js プロジェクトの package.json ファイルにコマンドを定義すること で呼び出せます。 { "scripts": { "build:pdf": "vivliostyle build --book -s JIS-B5 content/", "preview": "vivliostyle preview content/ --book" } } これは npm run build:pdf のように呼び出せます。 要素技術を組み合わせる 21

npm-scripts 2 npm-run-all というツールで npm-scripts のコマンド同⼠を簡単に組み合わせられます。 npm-run-all https://www.npmjs.com/package/npm-run-all これを利⽤して . Markdown ファイルを HTML 変換する . SCSS ファイルを CSS に変換する . 1 と 2 で⽣成されたものを Vivliostyle CLI で組版する を 1 コマンドで実⾏したりしています。便利ですね。 要素技術を組み合わせる 22

共同執筆 共同執筆 23

GitHub 要素技術が揃ったので、これらを組み合わせた合同誌プロジェクトを GitHub リポジトリーと して⽤意します。冒頭で紹介した https://github.com/spring-raining/tbf07-draft https://github.com/spring-raining/tbf08-draft などがそれです。執筆陣はこのリポジトリーを利⽤して編集してゆきます。 共同執筆 24

執筆 執筆者は前述のリポジトリーを GitHub 上で fork します。 akabekobeko/tbf08-draft https://github.com/akabekobeko/tbf08-draft これを git clone してから、プロジェクト内に content/akabeko のような感じで⾃分の ディレクトリーを作成します。 この中に index.md という名前の Markdown ファイルを置けば HTML 変換の対象となるの で、原稿を編集してゆきましょう。画像などが必要なら、それらも同じディレクトリー内に ⼊れておくと参照しやすくてよいです。  共同執筆 25

投稿 投稿は GitHub の Pull Request 機能を利⽤します。この辺は⻑くなるので以下のページを参 照してください。 プルリクエストの作成⽅法 - GitHub ヘルプ https://help.github.com/ja/github/collaborating-with-issues-and-pull- requests/creating-a-pull-request#further-reading プルリクエストとは？｜サルでもわかるGit⼊⾨【プロジェクト管理ツールBacklog】 https://backlog.com/ja/git-tutorial/pull-request/01/ 難しければ原稿ファイルを GitHub 操作に詳しい執筆者に渡して、操作を代⾏してもらうのも よいでしょう。 投稿 26

VFM と Vivliostyle Pub VFM と Vivliostyle Pub 27

VFM 合同誌の執筆で採⽤した Markdown 記法は必要に応じて拡張しました。しかし明確な仕様や 運⽤⽅針がないため どのような記法が有効なのか分からない 必要な記法の追加⽅法が不明確、プログラムを修正する？ などの問題があります。これを解決するために Vivliostyle としての Markdown を定義するこ とにしました。これを VFM (Flavored Markdown) と呼びます。 VFM と Vivliostyle Pub 28

VFM の仕様策定 VFM の記法や機能などの仕様は以下の GitHub リポジトリーで策定を進めています。 Issues https://github.com/vivliostyle/vfm/issues Working Draft https://github.com/vivliostyle/vfm/blob/master/spec/vfm.md 興味があれば議論に参加してみてください！ 個⼈的には Working Draft の Walled block が気になっています。HTML 埋め込みが可能だと しても最⼩限にしたい勢としては要注⽬の記法です。 VFM と Vivliostyle Pub 29

Vivliostyle Pub ここまでの登壇を聞いて、⾃分も同じような環境で執筆したいと考えた⽅がいらっしゃるか もしれません。 しかしプログラミングや GitHub 操作に慣れていないとハードルは⾼いと思います。 この問題を解決するために Vivliostyle Pub という Web サービスの⽴ち上げを計画していま す。 VFM と Vivliostyle Pub 30

Vivliostyle Pub 概要 詳細は他の登壇にゆずりますが、⼤まかには Web ブラウザーだけで執筆、Web 公開、PDF 出⼒、⼊稿までを完結可能 本登壇で紹介したような環境が⽤意されている、⾃分で構築しなくてもよい VFM で執筆可能 ...etc となります。お楽しみに！ このスライドは Marp というツールで作成しましたが、将来は Pub で書いて発表したいです ね。そういう機能も検討しています。 VFM と Vivliostyle Pub 31

ご清聴 ありがとうございました Vivliostyle CLI による合同誌作り 32