docs.vivliostyle.org

Create Book

はじめに

Create Book は、簡単に本を作れる環境を構築します。テンプレートをつかって原稿を執筆し、各種のカスタマイズをした後、Vivliostyle CLI により本を生成します。専門的な HTML や CSS の知識は必要ありません。

本文書では、複数のページを綴じた PDFファイルを一括して「本」と呼びます。 Vivliostyle はさまざまな形の本を作るためのライブラリです。より多くのユーザに、より簡単に Vivliostyle の技術を届けるプロダクトが Create Book です。

本文書が対象とするバージョン

本文書の読者対象

Create Bookの動作環境

本を作る手順

以下の手順により本を作成することができます。

  1. Create Book を実行し、プロジェクトフォルダを作成
  2. 作成されたプロジェクトフォルダに移動
  3. 既存の markdown ファイルを編集して原稿を執筆
  4. vivliostyle.config.js を編集してカスタマイズ
  5. npm により Vivliostyle CLI を実行し本を生成

作成されるプロジェクトフォルダは git で管理されるため、SourceTree などの git クライアントを使えば、現在の版と以前の版を比較したり戻したりといった、バージョン管理による本作りができます (もしバージョン管理が不要でしたら、無視しても全く問題ありません)。なお、本文書では git の解説はしません。各種解説書、解説サイトをご参照ください。

インストール

プロジェクトフォルダを作成するインストールコマンドは下記の通りです。<directory> には作成しようとする本のプロジェクトフォルダ名を指定します。非ASCII文字は使えません。

npm create book <directory>

指定したプロジェクトフォルダが既に存在しており、且つそのフォルダが空でない場合、 Create Book はエラーになります(既存のフォルダが空であればインストールは成功します)。

なお、npm以外に yarnも利用可能ですが、本文書ではより一般的な前者で説明します。

インストールの際、以下の項目を指定することができます (図1)。必ずしもここで全てを指定する必要はなく、指定したくない場合はリターンキーで次の項目に移動できます。後述の vivliostyle.config.js を編集することで変更が可能です。

![](/images/tutorial-CB-fig1.png)
図1 Create Bookのインストール。プロジェクトフォルダ名として mybook を指定している。なお、npmから警告が出るがユーザに影響はない。

なお、テーマパッケージもOSS開発です。開発が進むにつれ、上記以外にも追加される可能性があります。

Create Book の仕組み

下図は実際にインストールしたプロジェクトフォルダ (ここでは mybook) の内容です (図2)。自分の意図に合わせて本を作るため、❶〜❸のファイルを編集します。

![](/images/tutorial-CB-fig2.png)
図2 インストールにより生成されたmybookフォルダの内容。なお、グレイのファイル/フォルダは不可視属性。

Create Book は JavaScript の実行環境の一つである Node.js に付属するコマンドラインインターフェイス、npmによって本作りをします。Create Book はインストールの際、以下のようなことをします。

npm は上記設定ファイルを参照し、また上記ライブラリを使いながら、Vivliostyle CLI を駆動して manuscript.md を組版し、PDFファイルに出力します。

原稿の執筆

インストールすると作成される manuscript.md (図2❶) をテンプレートにして原稿を執筆します。記法は標準的な markdown であるGFM (GitHub Flavored Markdown)を、書籍向けに拡張した VFM (Vivliostyle Flavored Markdown) です。

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

GFM (GitHub Flavored Markdown)

下記の外部サイトを参照してください。

VFM (Vivliostyle Flavored Markdown)

詳細な仕様は下記を参照してください。

ただし、現バージョンでは以下の項目のみ実装しています。

その他の記法

GFM にも VFM にも規定されていませんが、下記外部サイトの記法でいくつかの 後注が利用できます。

また、テーマパッケージ @vivliostyle/theme-techbook を選択した場合、より煩雑にはなりますが、以下の記法で脚注が利用できます。

 <span class="footnote">text</span>

縦中横

テーマパッケージ @vivliostyle/theme-bunkoを選択すると、以下の記法で縦中横が書けるようになります。テーマパッケージの選択については、後述テーマパッケージの指定を参照してください。

ええと<span class="tcy">4</span>×<span class="tcy">5</span><span class="tcy">12</span><span class="tcy">4</span>×<span class="tcy">6</span><span class="tcy">13</span><span class="tcy">4</span>×<span class="tcy">7</span>——ああ、もう! そんな調子じゃいつまでも<span class="tcy">20</span>にならなくてよ!

本のカスタマイズ

vivliostyle.config.js (図2❷) を編集することで、次のようなカスタマイズが可能になります。

書名の指定

以下のように title を指定すると書名となります (値をシングルクォートで括る。以下同じ)。

title: 'mybook',

著者名とメールアドレスの指定

インストール時に author name で入力した著者名がデフォルトになりますが、以下のように指定すると、それが優先されます。

author: 'yamada <[email protected]>',

使用する言語の指定

language のコメントアウト (スラッシュ部分) を削除すると、本で使用する言語を指定できます。デフォルトの英語は en、日本語は ja。その他、 ISO 639-1に規定された2文字コードが指定できます。

// language: 'ja',

language: 'ja',

判型の指定

sizeのコメントアウトを削除すると判型を指定できます。CSS Paged Media Module Level 3 (7.1. Page size)に規定された下記の値が指定できます。なお、日本での一般的なB5は JIS-B5 ですのでご注意ください (B4も同様)。

// size: 'A4',

size: 'JIS-B5',

テーマパッケージの指定

インストール時に theme で指定したテーマパッケージがデフォルトで読み込まれますが、ここで任意のテーマパッケージを指定すると、そちらが優先されます。

theme: 'sample.css',

テーマパッケージは本のスタイルを定義したCSSファイルを含みます。仕様は下記を参照してください。

なお、テーマパッケージは下記から取得できます。

複数原稿の掲載

entry の部分で下記のように指定することで、複数の markdown ファイルをまとめて1冊にできます。

entry: [
    "filename1.md",
    "filename2.md",
    "filename3.md",
],

目次の追加

以下の手順で目次を追加することができます。

  1. あらかじめ以下のような目次用の markdown ファイルを用意し、ファイル名を index.md としてプロジェクトフォルダに保存します。なお、HTMLのタグがある行とmarkdownの行の間には、必ず空行をいれるよう注意してください。そうしないとエラーになります。
# 本のタイトル

<nav id="toc" role="doc-toc">

## 目次

- [記事タイトル1](filename1.html)
- [記事タイトル2](filename2.html)
- [記事タイトル3](filename3.html)

</nav>
  1. vivliostyle.config.jsentry の先頭行に、用意した index.md を指定します。
entry: [
    "index.md",
    "filename1.md",
    "filename2.md",
    "filename3.md",
],

奥付の追加

以下の手順で奥付を追加することができます。

  1. あらかじめ以下のような markdownファイルを用意し、ファイル名を colophon.md としてプロジェクトフォルダに保存します。なお、HTMLのタグがある行とmarkdownの行の間には、必ず空行をいれるよう注意してください。そうしないとエラーになります。
<section id="colophon" role="doc-colophon">

## 私が書いた本
20xx年x月x日 初版発行
- 発行 私が書いた本刊行会
- 編集 山田太郎
- 印刷 Sample Printing
© My Book Publishing, 20xx

</section>
  1. vivliostyle.config.jsentry の末尾行に、用意した colophon.md を指定します。
entry: [
    "index.md",
    "filename1.md",
    "filename2.md",
    "filename3.md",
    "colophon.md",
],

本の生成

npm スクリプトにより、Vivliostyle CLI を使って本を生成します。以下のコマンドを実行すると、プロジェクトフォルダと同名のPDFファイルを出力します。

なお、つづけて同じコマンドを実行すると、前回生成したPDFファイルは警告なく上書きされます。保存したい場合はあらかじめ別の場所に待避するようご注意ください。

npm run build
![](/images/tutorial-CB-fig3.png)
図3 Vivliostyle CLI を使った本の生成。

4色印刷用PDFファイル の生成

package.json (図2❸) を編集して、下記のように "vivliostyle build" の部分に --press-ready オプションを追加することで、PDF/X-1a規格に適合した4色印刷可能なPDFファイルを生成することができます。

"build": "vivliostyle build",

"build": "vivliostyle build --press-ready",

なお、このオプションを指定した際、データにドロップシャドウなど透明画像が含まれている場合に限って全体がラスタライズ(ビットマップ化)され、その結果文字の縁などにわずかな滲みが出ます。大きな問題にはなりませんが、不安な場合はあらかじめ印刷所にご相談ください。この現象は、Acrobat Pro DC 等により、PDF/X-4 に変換することで回避できます。

以下は生成時のキャプチャです (図4)。

![](/images/tutorial-CB-fig4.png)
図4 CMYK (4色) 印刷用のPDF/x-1aを出力。

制限事項

現在のバージョンでは、以下のような制限があります。

おわりに

バージョン番号をみてもお分かりのように、Create Book はまだ開発中。そして Vivliostyle のプロダクトはすべてオープンソース。こうなればいい、こんな機能はないの、こんなエラーが出たなどの感想や報告を、ぜひお寄せください。もちろん開発に加わりたい! も大歓迎。詳しくは下記のページをご覧ください。