はじめに

Vivliostyle CLIは、HTMLやマークダウン文書を組版するためのコマンドラインインターフェイスです。Vivliostyle Viewerを内蔵し、出版物に適した高品質なPDFを生成します。

Vivliostyleプロジェクトを作成する

次のいずれかのコマンドを実行してください。質問される内容に答えると、プロジェクトが自動的に作成されます。

npm create book
yarn create book # For yarn users
pnpm create book # For pnpm users

[!NOTE] 事前にNode.js（v20以上）のインストールが必要です。BunやDenoなどNode.js以外のランタイムを使用する場合は、それぞれのランタイムの使用手順にしたがってください。

プロジェクトを作成すると、自動的に vivliostyle.config.js という名前の構成ファイルが作成されます。詳しい使用方法は構成ファイルを参照してください。

コミュニティーテンプレート

Vivliostyle CLIはデフォルトでMinimal、Basic、Documentation、Novel、Academic、Magazineのテンプレートを用意しています。もし使いたいVivliostyle Themeが独自のテンプレートを提供している場合、プロジェクト作成ステップで Use templates from the community theme を選ぶことでそのテンプレートからプロジェクトを作り始めることができます。

また、自分で用意したテンプレートを使用することもできます。--template オプションで指定したテンプレートをもとにプロジェクトを作成します。

npm create book -- --template gh:org/repo/templates/awesome-template

テンプレートの参照方法はgigetのドキュメントを参照してください。

マニュアルインストール

次のコマンドでVivliostyle CLIをインストールできます。

npm install -g @vivliostyle/cli

上記のコマンドは、システム全体でVivliostyleを利用できるようにするものです。そうではなく、現在のディレクトリのみでVivliostyle CLIを利用する場合、以下のようにします。

npm install @vivliostyle/cli

PDFの生成

HTMLやMarkdownからPDFを生成

vivliostyle build コマンドでHTMLファイルを指定すると、HTMLから組版した結果のPDFファイルが出力されます。デフォルトで出力されるPDFファイル名は"output.pdf"です。

vivliostyle build index.html

同様に、Markdownファイルを指定するとMarkdownから組版した結果のPDFファイルが出力されます。

vivliostyle build manuscript.md -s A4 -o paper.pdf

Vivliostyle CLIで利用可能なMarkdown記法については、VFM: Vivliostyle Flavored Markdownを参照してください。

出力PDFファイルの指定

-o (--output)オプションでPDFファイル名を指定できます。

vivliostyle build book.html -o book.pdf

WebのURLの指定

ローカルのHTMLファイルのほか、WebのURLを指定することもできます。

vivliostyle build https://vivliostyle.github.io/vivliostyle_doc/samples/gutenberg/Alice.html -s A4 -o Alice.pdf

他の形式からPDFを生成

EPUBや解凍されたEPUBのOPFファイル、pub-manifest（Web出版物のマニフェストJSONファイル）、webbook（目次やWeb出版物のマニフェストへのリンクがあるHTMLファイル）形式の読み込みに対応します。

vivliostyle build epub-sample.epub -o epub.pdf
vivliostyle build publication.json -o webpub.pdf

組版結果のプレビュー

vivliostyle preview コマンドで組版結果をブラウザでプレビューすることができます。プレビューを実行すると、ブラウザが立ち上がり組版結果をVivliostyle Viewerで閲覧することができます。

vivliostyle preview index.html
vivliostyle preview manuscript.md
vivliostyle preview epub-sample.epub

多数の文書から構成される出版物をすばやくプレビュー

多数の文書から構成される出版物をすばやくプレビューするためには、-q (--quick)オプションを指定してください。このオプションでは大まかなページ数カウントを使って迅速に文書をロードします（ページ番号の出力は不正確になります）。

vivliostyle preview index.html --quick
vivliostyle preview publication.json --quick
vivliostyle preview epub-sample.epub --quick

PDF形式以外の出力

Vivliostyle CLIはPDF形式以外にも、EPUB形式とWeb出版物（WebPub）の出力に対応します。詳細は特別な出力設定をご覧ください。

サポートする出力形式のマトリックスは以下の通りです。

入力\出力	`pdf`	`webpub`	`epub`
`pub-manifest`	🔵	🔵	🔵
`markdown`	🔵	🔵	🔵
`html` `webbook` (外部HTMLを含む)	🔵	🔵	🔵
`epub` `epub-opf`	🔵	🙅	🙅

その他のオプション

vivliostyle help コマンドでVivliostyle CLIで利用可能なオプションの一覧を表示できます。

vivliostyle help
vivliostyle help init
vivliostyle help build
vivliostyle help preview

秘密の機能: vivliostyle というコマンドの代わりに vs というコマンド名でも使用できるので、タイプ数を少し減らせます。

以下もご覧ください:

Vivliostyle CLI (README)