テンプレート

テンプレートを使用する

プロジェクト作成時に --template オプションでテンプレートを指定できます：

vivliostyle create my-project --template gh:org/repo/templates/awesome-template

npm create book でも同様に指定できます：

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

ビルトインテンプレート

Vivliostyle CLI には以下のプリセットが付属しています：

これらのプリセットは vivliostyle create を対話形式で実行したときに選択するか、直接指定することもできます：

vivliostyle create my-project --template minimal

テンプレートソースの種類

--template オプションには次の 3 種類の形式を指定できます。

# GitHub から取得
--template gh:org/repo/templates/my-template

# 特定のブランチまたはタグを指定
--template gh:org/repo/templates/my-template#v2.0.0

# GitLab から取得
--template gitlab:org/repo/templates/my-template

--template ./my-custom-template
--template ../shared-templates/book-template

テンプレート変数

テンプレートのファイルには Handlebars 式を埋め込むことができ、プロジェクト作成時に実際の値に置き換えられます。UTF-8 のテキストファイルのみが処理対象で、バイナリファイル（画像など）はそのままコピーされます。

// @ts-check
import { defineConfig } from '@vivliostyle/cli';

export default defineConfig({
  title: "{{proper title}}",
  author: "{{author}}",
  {{#if language}}
  language: "{{language}}",
  {{/if}}
  {{#if theme}}
  theme: {{json theme}},
  {{/if}}
  image: "ghcr.io/vivliostyle/cli:{{cliVersion}}",
  entry: ["manuscript.md"],
});

{
  "name": "{{kebab title}}",
  "description": "{{proper title}}",
  "author": "{{author}}",
  "version": "0.0.0",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "vivliostyle build",
    "preview": "vivliostyle preview"
  },
  "dependencies": {
    "@vivliostyle/cli": "{{cliVersion}}"
  }
}

Theme パッケージでテンプレートを提供する

Vivliostyle Themes のパッケージには、1 つ以上のプロジェクトテンプレートをバンドルできます。テンプレートは package.json の vivliostyle.template フィールドで宣言します：

{
  "name": "my-vivliostyle-theme",
  "version": "1.0.0",
  "vivliostyle": {
    "theme": {
      "name": "My Theme",
      "style": "./theme.css"
    },
    "template": {
      "default": {
        "name": "デフォルトテンプレート",
        "description": "基本的なスタート地点",
        "source": "org/my-vivliostyle-theme/template/default"
      },
      "with-prompts": {
        "name": "カスタムオプション付きテンプレート",
        "source": "org/my-vivliostyle-theme/template/with-prompts",
        "prompt": [
          {
            "type": "text",
            "name": "subtitle",
            "message": "サブタイトルを入力してください：",
            "required": false
          },
          {
            "type": "select",
            "name": "pageSize",
            "message": "ページサイズを選択してください：",
            "options": ["A4", "A5", "B5"]
          }
        ]
      }
    }
  }
}

vivliostyle.template の各キーはテンプレート ID です。値のオブジェクトには以下のフィールドがあります：

source フィールドには --template オプションと同じく giget 形式でダウンロードするテンプレートを指定します。

{
  "type": "text",
  "name": "subtitle",
  "message": "サブタイトルを入力してください：",
  "placeholder": "（省略可）",
  "defaultValue": "",
  "initialValue": "",
  "required": false
}

{
  "type": "select",
  "name": "pageSize",
  "message": "ページサイズを選択してください：",
  "options": [
    { "value": "A4", "label": "A4（210×297 mm）", "hint": "標準" },
    { "value": "A5", "label": "A5（148×210 mm）" },
    "B5"
  ],
  "initialValue": "A4"
}

{
  "type": "multiSelect",
  "name": "features",
  "message": "含める機能を選択してください：",
  "options": ["toc", "cover", "bibliography"]
}

{
  "type": "autocomplete",
  "name": "locale",
  "message": "ロケールを選択してください：",
  "options": ["en", "ja", "zh", "fr", "de"]
}

{
  "type": "autocompleteMultiSelect",
  "name": "locales",
  "message": "対応するロケールを選択してください：",
  "options": ["en", "ja", "zh", "fr", "de"]
}

my-vivliostyle-theme/
├── package.json               # vivliostyle.template を宣言
├── theme.css
└── template/
    └── default/
        ├── vivliostyle.config.js   # {{title}}、{{author}} などを使用
        ├── manuscript.md
        └── assets/
            └── cover.webp          # バイナリファイルはそのままコピー

ミニマルテンプレートの例

最小構成のテンプレートの例として、Markdown ファイル 1 つと設定ファイルだけで構成された例を示します。

vivliostyle.config.js：

// @ts-check
import { defineConfig } from '@vivliostyle/cli';

export default defineConfig({
  title: "{{proper title}}",
  author: "{{author}}",
  entry: ["manuscript.md"],
});

manuscript.md：

# {{proper title}}

ユーザーが vivliostyle create my-book --title "はじめての本" --author "山田 太郎" を実行すると、次のように置き換えられます：

vivliostyle.config.js（置き換え後）：

// @ts-check
import { defineConfig } from '@vivliostyle/cli';

export default defineConfig({
  title: "はじめての本",
  author: "山田 太郎",
  entry: ["manuscript.md"],
});