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

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

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

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

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

設定ファイル

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

package.json

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

vivliostyle.config.js

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

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

export default defineConfig({
  title: 'Mybook',
  author: '山田太郎',
  language: 'ja',
  size: 'A4',
  theme: [
    '@vivliostyle/theme-techbook',
    './custom.css',
  ],
  image: 'ghcr.io/vivliostyle/cli:10.3.1',
  entryContext: 'draft',
  entry: [
    {
      rel: 'cover',
      path: '01_cover.md',
      output: 'cover.html',
      theme: './cover.css',
    },
    { rel: 'contents' },
    '02_introduction.md',
    '03_vfm-guide.md',
    '04_features.md',
    '05_examples.md',
    '06_styling-guide.md',
    '07_advanced-features.md',
    '08_page-design.md',
    '09_distribution.md',
  ],
  toc: {
    sectionDepth: 1,
  },
  cover: {
    src: 'cover-image.webp',
  },
});

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

参照：Vivliostyle CLI ドキュメント（docs.vivliostyle.org）

原稿ファイル

Markdown 記法を拡張した VFM 記法で記述できます。HTML による記述も可能です。entryContext: 'draft' により、原稿ファイルのルートは draft/ ディレクトリです。スターターコンテンツの 03_vfm-guide.md には、見出し、ルビ、数式、frontmatter などの VFM 記法のガイドが含まれています。

スタイルファイル

出版物のスタイルを定義するスタイルファイルは CSS で記述します。Basic (Japanese) テンプレートには custom.css が含まれており、CSS Custom Properties がコメントアウトされた状態で一覧記載されています。コメントを外して値を変更するだけでスタイルをカスタマイズできます。表紙ページ専用のスタイルは cover.css です。

ベースのテーマには @vivliostyle/theme-techbook が適用され、custom.css で上書きする仕組みになっています。

カスタマイズ

前回のチュートリアルではスターターコンテンツから PDF を作成していました。今回はスターターコンテンツを自分の原稿に置き換え、custom.css を編集してスタイルをカスタマイズしてみましょう。

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

原稿ファイルは、vivliostyle.config.js の entry で設定した値に対応しています。Basic テンプレートの entry は次のような構造です。

entry: [
  {
    rel: 'cover',
    path: '01_cover.md',
    output: 'cover.html',
    theme: './cover.css',
  },
  { rel: 'contents' },
  '02_introduction.md',
  '03_vfm-guide.md',
  '04_features.md',
  '05_examples.md',
  '06_styling-guide.md',
  '07_advanced-features.md',
  '08_page-design.md',
  '09_distribution.md',
],

• rel: 'cover' は表紙ページ用の特殊エントリです
• { rel: 'contents' } は自動目次のエントリです
• 通常の章はファイル名の文字列だけで指定できます

原稿を増やす例

entry: [
  // ...既存エントリ...
  '09_distribution.md',
  '10_my-new-chapter.md',
],

draft/10_my-new-chapter.md を新規作成し、entry に追記します。

原稿を減らす例

entry: [
  { rel: 'cover', path: '01_cover.md', output: 'cover.html', theme: './cover.css' },
  { rel: 'contents' },
  '02_introduction.md',
  // '03_vfm-guide.md',
  // '04_features.md',
  // ...
],

不要な章を entry から削除すれば、必要な章だけの出版物を作成できます。

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

Basic テンプレートの custom.css を開いてみましょう。CSS Custom Properties の一覧がコメントアウトされた状態で記載されています。コメントを外して値を変えるだけで、スタイルを簡単にカスタマイズできます。

実際の例①: 見出しフォントの変更

:root {
  --vs--heading-font-family: 'Helvetica Neue', sans-serif;
}

実際の例②: セクション番号の有効化

この属性は custom.css に・リストされていないため、以下のルールを custom.css に追記します。

:root {
  --vs-section--marker-display: inline;
}

実際の例③: ページ番号の表示

:root {
  --vs-page--mbox-content-bottom-center: counter(page);
}

実際の例④: 段組みの設定

これらの属性は custom.css にリストされていないため、以下のルールを custom.css に追記します。

:root {
  --vs-columns: 2;
  --vs-column-gap: 2em;
}

特定のセクションだけ段組みにしたい場合は、カスタムクラスを custom.css の末尾に追加します。

.two-column {
  column-count: 2;
  column-gap: 2em;
  column-rule: 1px solid #e0e0e0;
}

Markdown 内で <div class="two-column">...</div> として使用できます。スターターコンテンツの 06_styling-guide.md（Two-Column Layouts）と 08_page-design.md（Multi-Column Layouts）にも詳しいガイドがあります。

npm run preview を起動した状態で CSS を保存すると、プレビュー画面が更新されます。変更前後を見比べて確認してください。

補足: より高度なカスタマイズ

CSS Custom Properties で対応できないスタイル変更が必要な場合は、custom.css に独自の CSS ルールを追加できます。より詳細な用紙や文字の設定は次のチュートリアルで扱います。

まとめ

このチュートリアルを通して、Basic テンプレートの構造を理解し、原稿ファイルの管理方法とスタイルのカスタマイズ方法を学びました。次のチュートリアルでは、CSS を使ってより詳細な用紙と文字の設定を行います。

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

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