チュートリアル③原稿とテーマのカスタマイズ

このチュートリアルの目標

• PDF の作成に必要なファイルがわかる
• 設定ファイルの構造がわかる
• 原稿ファイル・既存テーマのカスタマイズ方法がわかる

PDF の作成に必要なファイル

前回のチュートリアルで作成した雛形には、PDF の作成に必要なファイル（設定ファイル、原稿ファイル、スタイルファイル）が全て含まれています。

設定ファイル

Create Book を使って出版物を作成するには、package.json と vivliostyle.config.js という2つの設定ファイルが必要になります。

package.json

出版物を作成するためのコマンド、必要なリソースのバージョンなどをまとめた設定ファイルです。編集する機会は基本的にありません。

vivliostyle.config.js

出版物に関する設定ファイルです。雛形作成時に設定した項目もこのファイルで管理されています（上書き可能です）。原稿ファイルを増やしたい時や、テーマを別のものに変えたい時は、このファイルを編集します。

module.exports = {
  title: 'mybook',
  author: '山田太郎 <[email protected]>',
  language: 'ja',
  theme: '@vivliostyle/theme-bunko',
  entry: [
    'bunko.md',
    {
      path: 'epigraph.md',
      title: 'Epigraph',
      theme: '@vivliostyle/theme-whatever',
    },
    'glossary.html',
  ],
  entryContext: './manuscripts',
  output: [
    './output.pdf',
    {
      path: './book',
      format: 'webpub',
    },
  ],
  workspaceDir: '.vivliostyle',
  toc: true,
  cover: './cover.png',
  vfm: {
    hardLineBreaks: true,
    disableFormatHtml: true,
  },
}

vivliostyle.config.js では、以下の項目を設定できます。

詳細は Vivliostyle CLI ドキュメントを参照してください。

原稿ファイル

Markdown 記法を拡張した VFM 記法で記述できます。HTML による記述も可能です。原稿を変更したい場合は、このファイルを編集したり、新しくファイルを追加したりします。

スタイルファイル

出版物のスタイルを定義するスタイルファイルは SCSS で記述され、CSS にトランスパイルされて使用されます。詳細は Vivliostyle Themes ドキュメントを参照してください。

多くの場合、スタイルファイルは複数のファイルからなり、1つのディレクトリに格納されています。例えば、雛形作成時に選択したテーマは themes/packages/@vivliostyle/theme-bunko という名前のディレクトリにダウンロードされています。出版物のスタイルを変更したい場合は、これらのファイルを編集したり、新しくファイルを追加したりします。

カスタマイズ

前回のチュートリアルではサンプル原稿を直接編集して PDF を作成していました。また、スタイルには既存のテーマ @vivliostyle/theme-bunko が適用されていました。今回はサンプル原稿ではなく、自分で新しい原稿を用意してみましょう。さらに、既存テーマをカスタマイズして PDF を作成してみましょう。

原稿ファイルのカスタマイズ

原稿ファイルは、vivliostyle.config.js の entry で設定した値に対応しています。例えば vivliostyle.config.js で以下のような設定をした場合、

module.exports = {
  ...
  entry: [
    'maegaki.md',
    'honbun.md',
    'atogaki.md',
  ],
  entryContext: './manuscripts',
  ...
}

• 原稿ファイルは maegaki.md と honbun.md と atogaki.md の3つ
• 原稿ファイルは全て ./manuscripts というディレクトリに含まれている

という条件で PDF が作成されます。

では、この条件で作成される PDF をプレビューしてみましょう。以下のボタンから vivliostyle.config.js および原稿ファイルをダウンロードし、mybook ディレクトリの中に置いてみましょう。

1. vivliostyle.config.js
2. manuscripts.zip

mybook/
├── package.json
├── vivliostyle.config.js (*既存のファイルを上書き)
├── manuscripts/ (*)
│   ├── maegaki.md
│   ├── honbun.md
│   └── atogaki.md
└── themes/
    └── packages/
        └── @vivliostyle/
            └── theme-bunko/

プレビュー機能を起動すると、vivliostyle.config.js で指定した通りの順番で、原稿ファイルが出版物に反映されていることがわかります（反映されない場合は、 npm run preview が実行されているターミナルで Ctrl+C を入力してコマンドの実行を停止し、再度 npm run preview を実行してください）。

npm run preview

このように、原稿ファイルを増やしたいときは、

1. 新しい原稿ファイルを作成
2. vivliostyle.config.js の entry に追記

という手順を踏みます。

既存テーマのカスタマイズ

vivliostyle.config.js の theme には、npm package として公開されているテーマの名前、スタイルファイルを格納したディレクトリの名前、または特定のスタイルファイルの名前を設定します。デフォルトでは vivliostyle.config.js で以下のように設定されています。

module.exports = {
  ...
  theme: '@vivliostyle/theme-bunko',
  ...
}

この場合、

• 原稿ファイルには @vivliostyle/theme-bunko という名前の npm package のテーマを適用する

という設定で PDF が作成されます。

では、既存のテーマ @vivliostyle/theme-bunko をカスタマイズし、そのスタイルを PDF に適用してみましょう。既存のテーマを改造する場合は、既存のテーマのディレクトリ (themes/packages/@vivliostyle/theme-bunko) をコピーし、別の名前をつけて保存します。

mybook/
├── package.json
├── vivliostyle.config.js
├── manuscripts/
│   ├── maegaki.md
│   ├── honbun.md
│   └── atogaki.md
└── themes/
    ├── mytheme/ (*theme-bunkoをコピー)
    └── packages/
        └── @vivliostyle/
            └── theme-bunko/

その後、vivliostyle.config.js の theme を、コピーしたディレクトリの名前に書き換えます。

module.exports = {
  ...
  theme: 'themes/mytheme',
  ...
}

すると、

• 原稿ファイルには ./themes/mytheme という名前のディレクトリで定義されているテーマを適用する

という設定で PDF が作成されます。

以降はこの mytheme を編集していきます。スタイルを編集する際は、mytheme ディレクトリに移動し、SCSS を CSS にトランスパイルするコマンドを実行しておきます。

# mytheme ディレクトリに移動するコマンド
cd themes/mytheme

# SCSS を CSS にトランスパイルするコマンド
npm run watch:scss

コマンドを実行すると以下のような表示が出ます（テーマによって、SCSS を CSS にトランスパイルするコマンドが異なる可能性があります。各テーマの package.json を確認してください）。

$ npm run watch:scss

> @vivliostyle/[email protected] watch:scss
> sass --watch scss:.

>>> Sass is watching for changes. Press Ctrl-C to stop.

手始めに、見出しの色を赤にしてみましょう。themes/mytheme/scss/theme_common.scss に以下を追記します。

h1 {
  color: red;
}

または以下のボタンから theme_common.scss をダウンロードし、mytheme/scss/theme_common.scss を置き換えます。

1. theme_common.scss

すると、npm run watch:scss が SCSS ファイルの変更を自動で検知して CSS ファイルを更新します。npm run preview は CSS ファイルの更新を検知して、プレビュー画面を更新します。プレビューを確認すると、意図した通りに、見出しの色が赤くなっていることがわかります。

このように、既存テーマをカスタマイズしたいときは、

1. 既存テーマのディレクトリをコピー
2. vivliostyle.config.js の theme を変更
3. npm run watch:scss で SCSS を CSS にトランスパイル

という手順を踏みます。

まとめ

このチュートリアルを通して、PDF の作成に必要なファイルを知り、原稿ファイル・既存テーマをカスタマイズできるようになりました。実際の執筆においても、複数の原稿ファイルを用意することや、テーマをカスタマイズする機会は多いと思います。

次のチュートリアルでは、SCSS を編集して用紙と文字の設定を行います。

• 前：チュートリアル②PDFの作成
• 次：チュートリアル④用紙と文字のスタイル
• チュートリアル一覧