テーマとCSS

原稿に対してフォントや文字の大きさなどの装飾を加えるには、カスケーディングスタイルシート（CSS）を適用します（HTMLファイルと同様のやり方です）。

スタイルシートの追加の指定

HTMLファイルに指定されているスタイルシートに加えて、追加のスタイルシート（CSSファイル）を使うには、--style オプションでスタイルシートを指定します。

vivliostyle build example.html --style additional-style.css

この方法で指定したスタイルシートは、HTMLファイルで指定されているスタイルシートと同様（作成者スタイルシート）の扱いで、よりあとに指定されたことになるので、CSSのカスケーディング規則により、HTMLファイルからのスタイルの指定を上書きすることになります。

ユーザースタイルシートの指定

ユーザースタイルシートを使うには、--user-style オプションでスタイルシートを指定します。（ユーザースタイルシートは、スタイル指定に !important を付けないかぎり、制作者スタイルシートのスタイル指定を上書きしません。）

vivliostyle build example.html --user-style user-style.css

CSSの内容を直接指定

--css オプションを指定すると、追加したいスタイルシートを直接CSSのテキストで渡すことができます。このオプションは、簡単なスタイルシートやCSS変数を設定するのに便利です。

vivliostyle build example.html --css "body { background-color: lime; }"

ページサイズの指定

-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

このオプションは、--css "@page { size: <size>; }" と同等です。

トンボ（crop marks）の指定

-m (--crop-marks)オプションを指定すると、出力されるPDFにトンボ（印刷物の裁断位置を示す目印）が追加されます。

vivliostyle build example.html -m

--bleed オプションでトンボを追加したときの塗り足し幅を指定することができます。また、--crop-offset オプションで裁ち落とし線から外側の幅を指定することができます。

vivliostyle build example.html -m --bleed 5mm
vivliostyle build example.html -m --crop-offset 20mm

このオプションは、--css "@page { marks: crop cross; bleed: <bleed>; crop-offset: <crop-offset>; }" と同等です。

Vivliostyle Themesについて

Vivliostyle Themes

Vivliostyle Themesは、Vivliostyleで出版物を作る際に使う公式のスタイルテーマ集です。Vivliostyle Themesを参照することで、自分でCSSを用意することなくスタイルを適用することができます。

テーマを見つける

npmパッケージとして公開されているテーマを見つけるにはnpmでキーワード"vivliostyle-theme"を検索してください:

List of Themes (npm)

テーマの利用

-T（--theme）オプション、または構成ファイルで theme を指定するとテーマを利用できます。ローカルにテーマファイルが存在しない場合、初回実行時に自動的にインストールされます。

vivliostyle build manuscript.md --theme @vivliostyle/theme-techbook -o paper.pdf

また、ローカル環境にあるテーマを利用することもできます。単一のCSSファイルであれば、以下のように直接CSSファイルを指定します。

vivliostyle build manuscript.md --theme ./my-theme/style.css -o paper.pdf

また、ローカル環境にnpmに準拠した package.json ファイルがある場合、そのディレクトリにあるVivliostyle Themeを読み込むこともできます。以下は my-theme ディレクトリにVivliostyle Themeとして利用可能なパッケージが配置されているときの例です。

vivliostyle build manuscript.md --theme ./my-theme -o paper.pdf

上記の設定はすべて構成ファイルで指定できます。また、複数使用することもできます。

theme: [
  '@vivliostyle/theme-techbook',
  './my-theme',
],

CSSからのテーマの読み込み

theme オプションでVivliostyle Themesを指定する代わりに、theme オプションで指定したCSSファイルからnpmパッケージ名でテーマを直接読み込むことができます:

@import '@vivliostyle/theme-base';
@import '@vivliostyle/theme-base/footnote';

h1 {
  /* 独自のカスタマイズ */
}

パッケージ名のみを指定した場合、そのパッケージのpackage.jsonの vivliostyle.theme.style、style、exports（style コンディション）、main フィールドをこの順で参照し、既定のスタイルファイルを読み込みます。サブパスを指定した場合は指定したファイルを読み込みます。パッケージが exports フィールドを宣言している場合、サブパスは exports を通して解決されます。

読み込んだパッケージは、theme オプションによる指定と同様に自動でインストールされます。パッケージ名の後にnpm形式の @ 記法を続けることで、インストールするバージョンを指定することもできます:

@import '@vivliostyle/theme-base@^3.0.0';

.css 拡張子を持つ既存のファイルを指す指定子は、相対URLとして標準のCSSの扱いが保たれます。例えば @import 'foo.css' は、読み込み元のスタイルシートの隣にfoo.cssが存在する場合、その相対パスのファイルを参照します。それ以外の指定子はnpmパッケージとして解決されます。同じパッケージがプロジェクトと themes ディレクトリの両方にインストールされている場合、themes ディレクトリのものが優先されます。

Create Bookの利用

Create Bookを使用すると、あらかじめテーマが設定された状態のプロジェクトを簡単に作成できます。Vivliostyleプロジェクトを作成するを参照してください。

PostCSSの利用

プロジェクトにPostCSSの設定ファイルがある場合、Vivliostyle CLIが処理するすべてのCSSファイルにそのプラグインが適用されます。

PostCSSの設定ファイルは、構成ファイルと同じディレクトリに配置してください。postcss-load-configがサポートする形式の設定（例: postcss.config.js）を読み込めます。この設定は、利用しているテーマパッケージのCSSファイルにも適用されます。

構成ファイルのcss.postcss オプションには、インラインのPostCSS設定、またはPostCSS設定ファイルを探索するディレクトリを指定できます。インライン設定を指定した場合、PostCSS設定ファイルの探索は行われません。

import autoprefixer from 'autoprefixer';

export default {
  entry: ['manuscript.md'],
  css: {
    postcss: {
      plugins: [autoprefixer()],
    },
  },
};

Tailwind CSS

Example: with-tailwindcss

PostCSSのプラグインを通して、Tailwind CSSなどのCSSフレームワークを利用することもできます。

Tailwind CSS公式ドキュメントのUsing PostCSSのセクションに従ってセットアップしてください。

Tailwind CSSは、ユーティリティクラスと呼ばれるクラスを要素に指定して、クラス名に応じたスタイルを適用するフレームワークです。VFMと組み合わせる場合は、以下のようにVFMの属性記法でクラスを指定できます。Tailwindが原稿ファイルをスキャンし、使われているクラスに対応するスタイルを生成します。

# Vivliostyle meets Tailwind CSS {.text-4xl .font-extrabold .tracking-tight .text-accent}

This document is styled with [Tailwind CSS](https://tailwindcss.com/) utility classes.
Tailwind scans this Markdown file for class names, so you can attach utilities to
inline elements with the **VFM attribute syntax**{.bg-accent/15 .px-1 .rounded} like
`**text**{.underline}`.

Tailwind CSSは強力なツールですが、Vivliostyleが主な対象とする文章中心のドキュメントはWebページと異なる点も多く、ユーティリティクラスによる指定が文章の制作に合うかどうかはあなたの執筆スタイルによります。とはいえ、本文中でアドホックなスタイルを多用したい場合には、有力な選択肢となるでしょう。

テーマの作成

独自のVivliostyle Themeを作成してnpmパッケージとして公開すると、他のユーザーも自分の出版物にそのテーマを適用できるようになります。

テーマパッケージの雛形を作成する

vivliostyle theme create コマンドは、新しいテーマパッケージの雛形を作成します。質問される内容に答えると、必要なファイルとディレクトリが生成されます。

vivliostyle theme create

Vivliostyle CLIをインストールしていない場合は、npm create vivliostyle-theme@latest を実行すると、インストールせずに同じコマンドを利用できます。

npm create vivliostyle-theme@latest
yarn create vivliostyle-theme # For yarn users
pnpm create vivliostyle-theme # For pnpm users

生成されるパッケージの構成は次のとおりです。

my-theme/
├── README.md
├── example/
│   ├── assets/
│   ├── 01_typography.md
│   ├── 02_figures-and-tables.md
│   └── 03_code-and-math.md
├── package.json
├── theme.css
└── vivliostyle.config.js

theme.css：テーマのスタイルシートです。@vivliostyle/theme-baseとその機能モジュールを読み込み、CSS変数で調整しています。
example/：見出し、リスト、脚注、図、表、コード、数式など、テーマがスタイルを定めるべき要素を網羅したサンプル原稿です。npm run example:preview を実行すると、テーマを適用したプレビューが開きます。
vivliostyle.config.js：サンプル原稿のプレビューとビルドに使う構成ファイルです。

テーマのメタデータ

テーマパッケージは package.json の vivliostyle.theme フィールドに自身の情報を記述します。Vivliostyle CLIはこのフィールドからスタイルシートの場所を取得します。それぞれのフィールドの詳細については、Vivliostyle Themesのドキュメントを参照してください。

{
  "name": "vivliostyle-theme-my-theme",
  "author": "John Doe <[email protected]>",
  "main": "theme.css",
  "keywords": ["vivliostyle", "vivliostyle-theme"],
  "vivliostyle": {
    "theme": {
      "name": "My Theme",
      "author": "John Doe",
      "style": "theme.css",
      "category": "novel",
      "topics": ["paperback"]
    }
  }
}

テーマパッケージはプロジェクトのテンプレートを提供することもできます。Themeパッケージでテンプレートを提供するを参照してください。

テーマパッケージを検証する

vivliostyle theme validate コマンドは、テーマパッケージが正しく設定されているかを確認します。テーマのディレクトリで実行するか、ディレクトリのパスを引数に指定します。

vivliostyle theme validate

vivliostyle フィールドのスキーマを検証したうえで、次の項目を報告します。

エラー：スタイルファイルが指定されていない、または指定されたファイルがパッケージ内に存在しない
警告：著者が指定されていない
警告：keywords に vivliostyle-theme が含まれていない
警告：vivliostyle.theme.category が既知のカテゴリではない

エラーがある場合はゼロ以外の終了コードで終了するため、prepublishOnly スクリプトやCIで利用できます。生成されたパッケージには、このコマンドを実行する validate スクリプトが含まれています。

テーマを公開する

テーマが完成したら、npm publish でnpmに公開します。vivliostyle-theme キーワードを持つテーマはnpmのテーマ一覧に表示され、create コマンドでも選択できるようになります。テーマの仕様や公式テーマ集への寄稿については、Vivliostyle Themesリポジトリを参照してください。