Themeの開発

create-vivliostyle-themeによる雛形生成

create-vivliostyle-theme CLIを使って、テーマプロジェクトの雛形を生成します。

npm create vivliostyle-theme <theme-name>

対話形式で以下の項目を入力します。

実行後、vivliostyle-theme-<theme-name> ディレクトリが生成されます。

生成されるファイル構成

vivliostyle-theme-<name>/
├── .gitignore
├── package.json          # パッケージ定義（vivliostyle.theme 設定を含む）
├── README.md             # テーマの説明・使い方
├── theme.css             # テーマのメイン CSS
├── vivliostyle.config.js # プレビュー用の設定ファイル
└── example/
    └── default.md        # サンプル原稿（VFM 形式）

各ファイルの役割:

theme.cssの編集

生成直後の theme.css にはtheme-baseの全モジュールインポートとCSS変数のカスタマイズ例が含まれています。

/* theme-base の全モジュールをインポート */
@import url(../@vivliostyle/theme-base/theme-all.css);

/* コードハイライト（Prism）を追加 */
@import url(../@vivliostyle/theme-base/css/lib/prism/base.css);
@import url(../@vivliostyle/theme-base/css/lib/prism/theme-okaidia.css);

:root {
  /* 基本スタイル */
  --vs-font-family: 'Times New Roman', serif;
  --vs-font-size: 12px;
  --vs--heading-line-height: 1.3;
  --vs--h1-font-size: 2.5em;

  /* 脚注 */
  --vs-footnote--call-content: '[' counter(footnote) ']';

  /* ページレイアウト */
  --vs-page--mbox-content-bottom-center: counter(page);
  --vs-page--mbox-content-top-left: env(doc-title);

  /* 目次 */
  --vs-toc--marker-margin-inline: 8rem;
}

独自のスタイルを追加するには、このファイルの末尾にルールを記述します。ページサイズの設定例:

@page {
  size: A5;
  margin: 20mm 15mm;
}

theme-baseのモジュール活用

theme-baseは機能ごとにモジュール分割されています。全モジュールが不要な場合は、theme-all.css の代わりに必要なモジュールのみをインポートできます。

/* 基本モジュールのみ */
@import url(../@vivliostyle/theme-base/css/common/meta-properties.css);
@import url(../@vivliostyle/theme-base/css/common/reset.css);
@import url(../@vivliostyle/theme-base/css/common/basic.css);

/* 必要な機能モジュールを追加 */
@import url(../@vivliostyle/theme-base/css/partial/toc.css);
@import url(../@vivliostyle/theme-base/css/partial/footnote.css);

利用可能なモジュール一覧:

詳細は theme-baseのREADME を参照してください。

CSS変数のオーバーライド

theme-baseや各テーマが公開するCSS変数を :root で上書きすることで、テーマをカスタマイズできます。

:root {
  /* フォント設定 */
  --vs-font-family: 'Noto Serif JP', serif;
  --vs-font-size: 10.5pt;

  /* 見出し */
  --vs--h1-font-size: 2em;
  --vs--heading-line-height: 1.4;

  /* 相互参照のカウンタスタイル */
  --vs-crossref--counter-style: upper-roman;

  /* ページヘッダ・フッタ */
  --vs-page--mbox-content-top-left: env(pub-title);
  --vs-page--mbox-content-top-right: env(doc-title);
  --vs-page--mbox-content-bottom-center: counter(page);
}

実際のテーマでの活用例として、theme-techbook はテーマ固有のCSS変数（--vs-theme--*）を公開しています:

:root {
  --vs-theme--anchor-color-body: #3498db;
  --vs-theme--blockquote-color-bg: #ecf0f1;
  --vs-theme--inline-code-color-bg: #ecf0f1;
  --vs-theme--image-resolution-for-figure-image: 300dpi;
  --vs-theme--page-top-left-content: env(pub-title);
  --vs-theme--page-bottom-content: counter(page);
}

example/ ディレクトリの編集

example/ にはテーマの適用例を示すサンプルMarkdownを配置します。

• 最低1つのMarkdownファイルが必要です
• VFM (Vivliostyle Flavored Markdown) 記法が利用できます
• テーマが対応する主要なスタイル（見出し、コードブロック、脚注、画像、数式等）を網羅する内容を推奨します

プレビューで動作確認:

npm run preview

事前検証

公開前に vivliostyle-theme-scripts validate を実行して、パッケージの妥当性を検証します。

npm run validate

検証項目:

プレビュー確認

npm run preview

vivliostyle.config.js の設定に基づき、example/ のサンプル原稿にテーマを適用した状態でプレビューが表示されます。

package.jsonの必須フィールド

{
  "name": "vivliostyle-theme-<name>",
  "main": "theme.css",
  "keywords": ["vivliostyle", "vivliostyle-theme"],
  "vivliostyle": {
    "theme": {
      "name": "Theme Display Name",
      "author": "Author Name",
      "style": "theme.css",
      "category": "misc",
      "topics": []
    }
  }
}

詳細な仕様は Vivliostyle Themeの仕様 を参照してください。

npmへの公開

npm publish

公開後、テーマは以下から検索可能になります:

• GitHub Topics: vivliostyle-theme
• npm: vivliostyle-theme

公式テーマとして提案する

自作したテーマは、ぜひVivliostyle公式テーマとして提案してください。詳細は 公式Themeの採用 を参照してください。