Themeの開発

vivliostyle theme createによる雛形生成

Vivliostyle CLIでテーマプロジェクトの雛形を生成します。npm create vivliostyle-theme は同じコマンドのエイリアスです。

npx vivliostyle theme create <directory>
# または
npm create vivliostyle-theme <directory>

対話形式で以下の項目を入力します。いずれもコマンドラインオプションで指定できます。

生成されるファイル構成

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

各ファイルの役割:

theme.cssの編集

生成直後の theme.css は、theme-baseのモジュールをインポートし、CSS変数でカスタマイズする次のような構成になっています。

/* theme-base の基本モジュールをインポート */
@import '@vivliostyle/theme-base';

/* 機能モジュールをインポート */
@import '@vivliostyle/theme-base/appendix';
@import '@vivliostyle/theme-base/citation';
@import '@vivliostyle/theme-base/endnote';
@import '@vivliostyle/theme-base/equation';
@import '@vivliostyle/theme-base/figure';
@import '@vivliostyle/theme-base/footnote';
@import '@vivliostyle/theme-base/listing';
@import '@vivliostyle/theme-base/math';
@import '@vivliostyle/theme-base/page';
@import '@vivliostyle/theme-base/section';
@import '@vivliostyle/theme-base/sidenote';
@import '@vivliostyle/theme-base/table';
@import '@vivliostyle/theme-base/theorem';
@import '@vivliostyle/theme-base/toc';

/* コードハイライト（Prism）を追加 */
@import '@vivliostyle/theme-base/prism';
@import '@vivliostyle/theme-base/prism/theme-okaidia';

: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-bottom-center-content: counter(page);
  --vs-page--mbox-top-left-content: env(doc-title);

  /* 目次 */
  --vs-toc--ol-indent-size: 1.5rem;
}

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

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

theme-baseのモジュール活用

theme-baseは機能ごとにモジュール分割されています。パッケージエントリに含まれるのは基本モジュールだけなので、必要な機能モジュールのインポートだけを残せます。

/* 基本モジュールのみ */
@import '@vivliostyle/theme-base';

/* 必要な機能モジュールを追加 */
@import '@vivliostyle/theme-base/toc';
@import '@vivliostyle/theme-base/footnote';

利用可能なモジュール一覧（@vivliostyle/theme-base/<サブパス> でインポート）:

詳細は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-counter-style: upper-roman;

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

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

:root {
  --vs-theme-techbook--inline-code-color-bg: #ecf0f1;
  --vs-theme-techbook--inline-code-color-body: #34495e;
  --vs-theme-techbook--footnote-color-bg-on-screen: #e6f6d7;
  --vs-theme-techbook--image-resolution-for-figure-image: 300dpi;
}

example/ディレクトリの編集

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

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

プレビューで動作確認:

npm run example:preview

事前検証

公開前に vivliostyle theme validate を実行して、パッケージの妥当性を検証します。生成された雛形では npm run validate に割り当てられています。

npm run validate

検証項目:

プレビュー確認

npm run example: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の採用を参照してください。