Vivliostyle CLI
Vivliostyle CLI は、HTMLやマークダウン文書を組版するためのコマンドラインインターフェイスです。
インストール
事前に Node.js (v14 以上) のインストールが必要です。
次のコマンドで Vivliostyle CLI をインストールできます:
npm install -g @vivliostyle/cli
npm install -g @vivliostyle/cli
HTML から PDF を生成
vivliostyle build
コマンドで HTML ファイルを指定すると、HTML から組版した結果の PDF ファイルが出力されます。
vivliostyle build index.html
vivliostyle build index.html
デフォルトで出力される PDF ファイル名は "output.pdf" です。
出力 PDF ファイルの指定
-o
(--output
) オプションで PDF ファイル名を指定できます。
vivliostyle build book.html -o book.pdf
vivliostyle build book.html -o book.pdf
PDF を出力しないで結果を見るには
PDF を出力しないで組版結果を確認する方法については 組版結果のプレビュー を参照してください。
ページサイズの指定
-s
(--size
) オプションでページサイズを指定できます。指定できるサイズは、A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger のいずれか、またはコンマで区切って幅と高さを指定します。
vivliostyle build paper.html -s A4 -o paper.pdf
vivliostyle build letter.html -s letter -o letter.pdf
vivliostyle build slide.html -s 10in,7.5in -o slide.pdf
vivliostyle build paper.html -s A4 -o paper.pdf
vivliostyle build letter.html -s letter -o letter.pdf
vivliostyle build slide.html -s 10in,7.5in -o slide.pdf
Web の URL の指定
ローカルの HTML ファイルのほか、Web の URL を指定することもできます。
vivliostyle build https://vivliostyle.github.io/vivliostyle_doc/samples/gutenberg/Alice.html -s A4 -o Alice.pdf
vivliostyle build https://vivliostyle.github.io/vivliostyle_doc/samples/gutenberg/Alice.html -s A4 -o Alice.pdf
単一 HTML 文書の指定
Vivliostyle CLI のデフォルトの動作では、コマンドラインで指定された HTML 文書内に、別の HTML 文書へのリンクからなる目次がある場合、または、出版物マニフェストへのリンクがある場合、複数文書で構成される出版物(webbook あるいは webpub)の組版処理を行います。 -d
(--single-doc
) オプションを指定するとこの動作が変わり、単一の HTML 文書のみ組版することができます。
vivliostyle build index.html --single-doc
vivliostyle build index.html --single-doc
スタイルシートの追加の指定
HTMLファイルに指定されているスタイルシートに加えて、追加のスタイルシート(CSSファイル)を使うには、--style
オプションでスタイルシートを指定します。
vivliostyle build example.html --style additional-style.css
vivliostyle build example.html --style additional-style.css
この方法で指定したスタイルシートは、HTMLファイルで指定されているスタイルシートと同様(制作者スタイルシート)の扱いで、よりあとに指定されたことになるので、CSSのカスケーディング規則により、HTMLファイルからのスタイルの指定を上書きすることになります。
ユーザースタイルシートの指定
ユーザースタイルシートを使うには、--user-style
オプションでスタイルシートを指定します。(ユーザースタイルシートは、スタイル指定に !important
を付けないかぎり、制作者スタイルシートのスタイル指定を上書きしません。)
vivliostyle build example.html --user-style user-style.css
vivliostyle build example.html --user-style user-style.css
EPUB から PDF を生成
vivliostyle build
コマンドで EPUB ファイルを指定すると、EPUB から組版した結果の PDF ファイルが出力されます。
vivliostyle build epub-sample.epub -s A5 --user-style epub-style.css -o epub-sample.pdf
vivliostyle build epub-sample.epub -s A5 --user-style epub-style.css -o epub-sample.pdf
EPUB 用のユーザースタイルシートの例
EPUB を好みのページスタイルにして組版するには、ユーザースタイルシートの指定が必要です。
EPUB 用のユーザースタイルシートの例: epub-style.css
@page {
margin: 10%;
@top-center { /* ページヘッダー */
writing-mode: horizontal-tb;
font-size: 75%;
content: string(title);
}
@bottom-center { /* ページフッター */
writing-mode: horizontal-tb;
font-size: 67%;
content: counter(page);
}
}
@page :first { /* 表紙ページ */
margin: 0;
@top-center {
content: none;
}
@bottom-center {
content: none;
}
}
title {
string-set: title content();
}
img { /* 画像がページに収まるように */
max-width: 100vw !important;
max-height: 100vh !important;
}
@page {
margin: 10%;
@top-center { /* ページヘッダー */
writing-mode: horizontal-tb;
font-size: 75%;
content: string(title);
}
@bottom-center { /* ページフッター */
writing-mode: horizontal-tb;
font-size: 67%;
content: counter(page);
}
}
@page :first { /* 表紙ページ */
margin: 0;
@top-center {
content: none;
}
@bottom-center {
content: none;
}
}
title {
string-set: title content();
}
img { /* 画像がページに収まるように */
max-width: 100vw !important;
max-height: 100vh !important;
}
解凍された EPUB から PDF を生成
解凍(unzip)された EPUB から PDF を生成するには、EPUB の OPF ファイルを指定します。
unzip epub-sample.epub
vivliostyle build item/standard.opf -s A5 --user-style epub-style.css -o epub-sample.pdf
unzip epub-sample.epub
vivliostyle build item/standard.opf -s A5 --user-style epub-style.css -o epub-sample.pdf
Markdown から PDF を生成
vivliostyle build
コマンドで Markdown ファイルを指定すると、Markdown から組版した結果の PDF ファイルが出力されます。
vivliostyle build manuscript.md -s A4 -o paper.pdf
vivliostyle build manuscript.md -s A4 -o paper.pdf
VFM (Vivliostyle Flavored Markdown) について
Vivliostyle CLI で利用可能な Markdown 記法については、VFM: Vivliostyle Flavored Markdown を参照してください。
テーマ CSS スタイルシートの指定
-T
(--theme
) オプションで CSS ファイルを指定することができます。
vivliostyle build manuscript.md --theme my-theme/style.css -o paper.pdf
vivliostyle build manuscript.md --theme my-theme/style.css -o paper.pdf
組版結果のプレビュー
vivliostyle preview
コマンドで組版結果をブラウザでプレビューすることができます(プレビューには Vivliostyle Viewer が使われます)
vivliostyle preview index.html
vivliostyle preview index.html
vivliostyle preview https://example.com --user-style my-style.css
vivliostyle preview https://example.com --user-style my-style.css
vivliostyle preview publication.json
vivliostyle preview publication.json
vivliostyle preview epub-sample.epub --user-style my-style.css
vivliostyle preview epub-sample.epub --user-style my-style.css
vivliostyle preview manuscript.md --theme my-theme/style.css
vivliostyle preview manuscript.md --theme my-theme/style.css
多数の文書から構成される出版物をすばやくプレビュー
多数の文書から構成される出版物をすばやくプレビューするためには、-q
(--quick
) オプションを指定してください。このオプションでは大まかなページ数カウントを使って迅速に文書をロードします(ページ番号の出力は不正確になります)。
vivliostyle preview index.html --quick
vivliostyle preview index.html --quick
vivliostyle preview publication.json --quick
vivliostyle preview publication.json --quick
vivliostyle preview epub-sample.epub --quick
vivliostyle preview epub-sample.epub --quick
Vivliostyle Themes について
Theme を見つける
npm パッケージとして公開されている Theme を見つけるには npm でキーワード "vivliostyle-theme" を検索してください:
Theme のインストール
Vivliostyle CLI で npm パッケージとして公開されている Theme を利用するには、そのインストールが必要です。
npm install @vivliostyle/theme-techbook
npm install @vivliostyle/theme-techbook
Create Book の利用
Vivliostyle Themes を利用するより簡単な方法は Create Book を使用することです。Create Book を参照してください。
構成ファイル vivliostyle.config.js
複数の記事や章ごとのファイルをまとめて1つの出版物を構成するには、構成ファイルを利用します。vivliostyle build
または vivliostyle preview
コマンドを実行するとき、カレントディレクトリに構成ファイル vivliostyle.config.js
があるとそれが使われます。
構成ファイルの作成
次のコマンドで構成ファイル vivliostyle.config.js
を作成することができます。
vivliostyle init
vivliostyle init
これでカレントディレクトリに vivliostyle.config.js
が生成されます。構成ファイルは JavaScript で記述され、これを編集することで様々な設定を変更できます。
構成ファイルの設定内容
構成ファイルの設定内容についてはファイル内のコメント(//
ではじまる)に説明があります。
- title: 出版物のタイトル。例:
title: 'Principia'
。 - author: 著者名。例:
author: 'Isaac Newton'
。 - language: 言語。例:
language: 'en'
。 この指定があると HTML のlang
属性に反映されます。 - size: ページサイズ。例:
size: 'A4'
。 - theme: CSS ファイルを指定します。例:
theme: 'style.css'
、または Vivliostyle Themes のパッケージ名を指定します。例:theme: '@vivliostyle/theme-techbook'
。 - entry: 入力の Markdown または HTML ファイルの配列を指定します。js
entry: [ 'introduction.md', 'chapter1.md', 'chapter2.md', 'glossary.html' ],
entry: [ 'introduction.md', 'chapter1.md', 'chapter2.md', 'glossary.html' ],
entry
の個別の要素にtitle
やtheme
の指定が可能です。jsentry: [ { path: 'about.md', title: 'About This Book', theme: 'about.css' }, ... ],
entry: [ { path: 'about.md', title: 'About This Book', theme: 'about.css' }, ... ],
- output: 出力先を指定。例:
output: 'output.pdf'
。デフォルトは{title}.pdf
。次のように複数の出力を指定することも可能:jsoutput: [ './output.pdf', { path: './book', format: 'webpub', }, ],
output: [ './output.pdf', { path: './book', format: 'webpub', }, ],
webpub
出力については Web 出版物 (webpub) を参照してください。 - workspaceDir: 中間ファイルを保存するディレクトリを指定。この指定がない場合のデフォルトはカレントディレクトリであり、Markdown から変換された HTML ファイルは Markdown ファイルと同じ場所に保存されます。例:
workspaceDir: '.vivliostyle'
- toc:
toc: true
を指定すると、目次を含む HTML ファイルindex.html
が出力されます。詳しくは 目次の作成 を参照してください。
印刷用 PDF(PDF/X-1a 形式)の生成
vivliostyle build
コマンドの --press-ready
オプションにより印刷入稿に適した PDF/X-1a 形式で出力することができます。
この機能を使うためには、事前に Docker のインストールが必要です。
PDF の「しおり」(Bookmarks) の生成
vivliostyle build
コマンドで出力される PDF には、目次の内容が「しおり」(PDF Bookmarks) として生成されます。PDF の「しおり」は、Adobe Acrobat のような PDF 閲覧ソフトで目次ナビゲーションに利用できます。
この「しおり」生成機能は、出版物に目次が含まれるときに有効になります。EPUB から PDF を生成 の場合には、EPUB に含まれる目次が使われます。それ以外については次の 目次の作成 を参照してください。
目次の作成
構成ファイルでの目次生成の指定
構成ファイル vivliostyle.config.js
に toc: true
の指定がある場合、目次 HTML ファイル index.html
が生成されて、それが出版物の先頭のファイルになります。
目次 HTML ファイルの名前を指定のものにするには toc:
にファイル名を指定します。例: toc: 'toc.html'
生成される目次 HTML ファイルの内容は次のようになります。
<html>
<head>
<title>Book Title</title>
<link href="publication.json" rel="publication" />
<link href="style.css" rel="stylesheet" />
</head>
<body>
<h1>Book Title</h1>
<nav id="toc" role="doc-toc">
<h2>Table of Contents</h2>
<ol>
<li><a href="prologue.html">Prologue</a></li>
<li><a href="chapter1.html">Chapter 1</a></li>
<li><a href="chapter2.html">Chapter 2</a></li>
<li><a href="chapter3.html">Chapter 3</a></li>
<li><a href="epilogue.html">Epilogue</a></li>
</ol>
</nav>
</body>
</html>
<html>
<head>
<title>Book Title</title>
<link href="publication.json" rel="publication" />
<link href="style.css" rel="stylesheet" />
</head>
<body>
<h1>Book Title</h1>
<nav id="toc" role="doc-toc">
<h2>Table of Contents</h2>
<ol>
<li><a href="prologue.html">Prologue</a></li>
<li><a href="chapter1.html">Chapter 1</a></li>
<li><a href="chapter2.html">Chapter 2</a></li>
<li><a href="chapter3.html">Chapter 3</a></li>
<li><a href="epilogue.html">Epilogue</a></li>
</ol>
</nav>
</body>
</html>
目次タイトルの指定
- 目次 HTML の
title
とh1
要素には、出版物のタイトル(構成ファイルのtitle
で指定)が出力されます。 - 目次タイトル(
nav
要素内の見出しh2
要素の内容 "Table of Contents")は、構成ファイルのtocTitle
で指定することができます。例:tocTitle: 'Contents'
。
目次を出版物の先頭以外の場所に出力するには
構成ファイル vivliostyle.config.js
の entry
の配列の要素として { rel: 'contents' }
を指定すると、その位置に目次 HTML ファイルが生成されます。
entry: [
'titlepage.md',
{ rel: 'contents' },
'chapter1.md',
...
],
toc: 'toc.html',
entry: [
'titlepage.md',
{ rel: 'contents' },
'chapter1.md',
...
],
toc: 'toc.html',
これで、出版物の先頭の HTML ファイルは titlepage.html
で、その次に目次の HTML ファイル toc.html
という順番になります。
目次を自分で作成するには
目次を自分で作成するには、次のように、構成ファイルの entry
の配列の要素として目次のファイルのパスと rel: 'contents'
を指定してください。
entry: [
'titlepage.md',
{
path: 'toc.html',
rel: 'contents'
},
'chapter1.md',
...
],
entry: [
'titlepage.md',
{
path: 'toc.html',
rel: 'contents'
},
'chapter1.md',
...
],
目次の作り方については W3C Publication Manifest 仕様に付属の Machine-Processable Table of Contents を参照してください。
Web 出版物 (webpub)
vivliostyle build
コマンドに -f
(--format
) オプションで webpub
を指定すると、Web 出版物 (webpub) を生成します。出力先 -o
(--output
) オプションには webpub を配置するディレクトリを指定します。
(以下の例では、入力の Markdown や HTML ファイルの指定は構成ファイル vivliostyle.config.js
に記述されているものとします)
vivliostyle build -o webpub/ -f webpub
vivliostyle build -o webpub/ -f webpub
生成された webpub ディレクトリ内には出版物マニフェスト publication.json
ファイルがあり、コンテンツの HTML ファイルの読み込み順などの情報が記述されています。W3C 標準仕様である Publication Manifest に準拠しています。
webpub は、Web 上で読むことができる出版物を作るのに使えます。また、次のように publication.json
ファイルを vivliostyle build
コマンドに指定することで、webpub から PDF を生成することができます。
vivliostyle build webpub/publication.json -o pdfbook.pdf
vivliostyle build webpub/publication.json -o pdfbook.pdf
また、次のように1回の vivliostyle build
コマンドで webpub と PDF の両方を生成することもできます。
vivliostyle build -o webpub/ -f webpub -o pdfbook.pdf -f pdf
vivliostyle build -o webpub/ -f webpub -o pdfbook.pdf -f pdf
その他のオプション
vivliostyle help
コマンドで Vivliostyle CLI で利用可能なオプションの一覧を表示できます。
vivliostyle help
vivliostyle help init
vivliostyle help build
vivliostyle help preview
vivliostyle help
vivliostyle help init
vivliostyle help build
vivliostyle help preview
以下もご覧ください: