テーマを作る

既存のテーマをベースに、独自のテーマを作成できます。まず手順を紹介し、その後テーマの内部構造を解説します。

手順

ここでは、組織共通の Base（corporate）を作り、それを元に独自の Style（my-theme）を作成する流れを紹介します。

1. プロジェクトを作成し、テーマをインストールする

ベースにしたいテーマを --with-base 付きでインストールし、Base と Style の全ファイルをプロジェクトにコピーします:

docs-gen init my-theme-project
docs-gen theme install default my-theme-project --with-base

docs-gen init my-theme-project
docs-gen theme install default my-theme-project --with-base

プロジェクトはこのようになります。

# Base: 共通レイアウト基盤
bases/standard/
├── templates/
│   ├── base.html              # 共通 HTML シェル（ヘッダー、フッター、スクリプト）
│   ├── page.html              # サイドバー付きコンテンツページ
│   └── portal.html            # ホームページ（全幅、サイドバーなし）
└── static/
    ├── js/main.js             # 検索、テーマ切り替え、言語切り替え
    └── favicon.svg            # サイトアイコン

# Style: テーマ固有のファイル
styles/default/
├── config.toml                # シンタックスハイライト設定
└── static/
    └── css/main.css           # すべてのスタイル

# Base: 共通レイアウト基盤
bases/standard/
├── templates/
│   ├── base.html              # 共通 HTML シェル（ヘッダー、フッター、スクリプト）
│   ├── page.html              # サイドバー付きコンテンツページ
│   └── portal.html            # ホームページ（全幅、サイドバーなし）
└── static/
    ├── js/main.js             # 検索、テーマ切り替え、言語切り替え
    └── favicon.svg            # サイトアイコン

# Style: テーマ固有のファイル
styles/default/
├── config.toml                # シンタックスハイライト設定
└── static/
    └── css/main.css           # すべてのスタイル

2. テーマに名前を付ける

コピーされた styles/default/ を styles/my-theme/ のようにリネームし、プロジェクトの config.toml でテーマ名を合わせます:

# my-theme-project/config.toml
[system]
theme = "my-theme"

# my-theme-project/config.toml
[system]
theme = "my-theme"

Base もリネームできます。例えば bases/standard/ を bases/corporate/ にリネームした場合、各 Style の config.toml で Base 名を合わせます:

# styles/my-theme/config.toml
[system]
base = "corporate"

# styles/my-theme/config.toml
[system]
base = "corporate"

リネーム後の構造です:

bases/corporate/
├── templates/
│   ├── base.html
│   ├── page.html
│   └── portal.html
└── static/
    ├── js/main.js
    └── favicon.svg

styles/my-theme/
├── config.toml
└── static/
    └── css/main.css

bases/corporate/
├── templates/
│   ├── base.html
│   ├── page.html
│   └── portal.html
└── static/
    ├── js/main.js
    └── favicon.svg

styles/my-theme/
├── config.toml
└── static/
    └── css/main.css

3. ファイルを編集する

プロジェクトにコピーされたファイルを編集します:

styles/my-theme/static/css/main.css — 色、フォント、レイアウトを変更
styles/my-theme/config.toml — シンタックスハイライトの設定を変更
bases/corporate/templates/*.html — HTML 構造を変更
bases/corporate/static/js/main.js — 動的機能を変更

4. テストする

docs-gen serve はファイルの変更を検知して自動でリロードします:

docs-gen serve my-theme-project

docs-gen serve my-theme-project

5. 不要なファイルを削除する

変更しなかったファイルは削除できます。削除したファイルはビルトインのデフォルトにフォールバックします。

テーマの構造: Base + Style

テーマは Base と Style の2つで構成されています:

Base — テンプレート（HTML）、JavaScript、アイコンなど、レイアウトの共通基盤
Style — CSS やハイライト設定など、テーマ固有のファイル

複数のテーマが同じ Base を共有できます。例えば default と monotone は CSS だけが異なり、Base は共通です。どの Base を使うかは、Style の config.toml で指定します:

# styles/default/config.toml
[system]
base = "standard"    # この Style は standard Base を使う

# styles/default/config.toml
[system]
base = "standard"    # この Style は standard Base を使う

Base

Base にはテンプレートと JavaScript が含まれています:

テンプレート — ヘッダー、サイドバー、フッターなど、ページの HTML 構造を定義
JavaScript — テンプレートと連携して、検索・テーマ切り替え・言語切り替えなどの動的機能を提供

bases/standard/
├── templates/
│   ├── base.html              # 共通 HTML シェル（ヘッダー、フッター、スクリプト）
│   ├── page.html              # サイドバー付きコンテンツページ
│   └── portal.html            # ホームページ（全幅、サイドバーなし）
└── static/
    ├── js/main.js             # 検索、テーマ切り替え、言語切り替え
    └── favicon.svg            # サイトアイコン

bases/standard/
├── templates/
│   ├── base.html              # 共通 HTML シェル（ヘッダー、フッター、スクリプト）
│   ├── page.html              # サイドバー付きコンテンツページ
│   └── portal.html            # ホームページ（全幅、サイドバーなし）
└── static/
    ├── js/main.js             # 検索、テーマ切り替え、言語切り替え
    └── favicon.svg            # サイトアイコン

テンプレート

bases/standard/templates/ に3つのテンプレートがあります（文法は Tera を参照）:

base.html — 共通の HTML シェル。ヘッダー、フッター、検索モーダル、テーマ検出スクリプトを含みます。他のテンプレートはすべてこれを継承します。
page.html — コンテンツページ用。base.html を継承し、セクションナビゲーション付きのサイドバーを追加します。
portal.html — ホームページ用（言語ルートの index.md）。base.html を継承し、全幅レイアウトでサイドバーはありません。

テンプレートを編集する際は、JavaScript が参照する HTML 要素やクラス名を変えないよう注意してください。

テンプレート変数

docs-gen がビルド時にテンプレートに渡す変数です。{{ site.title }} のように参照します。値はプロジェクトの config.toml やビルド処理から生成されます:

変数	説明
`site.title`	`config.toml` のサイトタイトル
`site.version`	バージョン文字列
`site.base_url`	完全なベースURL（`hostname` + `base_path`）
`site.base_path`	URLのベースパス
`site.footer_message`	フッターHTML
`site.nav`	ナビゲーションエントリ（各エントリは `label`、`path` または `url` を持つ）
`site.langs`	設定済み言語のリスト
`site.single_lang`	言語が1つだけのとき `true`
`page.title`	現在のページタイトル
`page.status`	ページステータス（例: `"draft"`）
`lang`	現在の言語コード
`lang_prefix`	言語パスプレフィックス（例: `"/en"`）。単一言語サイトでは空
`content`	レンダリング済みページHTML。エスケープせずに出力するには `\| safe` を使う
`nav`	サイドバーナビゲーションツリー（`page.html` 内）

Style

Style にはテーマの見た目を決めるファイルが含まれています:

CSS — 色、フォント、レイアウトの余白などすべてのビジュアルスタイル
config.toml — 使用する Base の指定と、シンタックスハイライトの設定

styles/my-theme/
├── config.toml       # [system] base = "standard" + ハイライト設定
└── static/
    └── css/main.css  # すべてのスタイル

styles/my-theme/
├── config.toml       # [system] base = "standard" + ハイライト設定
└── static/
    └── css/main.css  # すべてのスタイル

ライト/ダークモード

CSS はダークモードがデフォルトです。ライトモード用のスタイルは [data-theme="light"] セレクタで定義します:

/* ダークモード（デフォルト） */
:root {
    --bg-color: #1a1a2e;
}

/* ライトモード */
[data-theme="light"] {
    --bg-color: #ffffff;
}

/* ダークモード（デフォルト） */
:root {
    --bg-color: #1a1a2e;
}

/* ライトモード */
[data-theme="light"] {
    --bg-color: #ffffff;
}

シンタックスハイライト

コードブロックのハイライトテーマは config.toml で設定します:

[highlight]
dark_theme = "base16-eighties.dark"
light_theme = "InspiredGitHub"

[highlight]
dark_theme = "base16-eighties.dark"
light_theme = "InspiredGitHub"

ダークテーマ: base16-ocean.dark, base16-eighties.dark, base16-mocha.dark, Solarized (dark)

ライトテーマ: base16-ocean.light, InspiredGitHub, Solarized (light)

両方を設定すると、docs-gen は各コードブロックをダーク用・ライト用の2つの HTML として出力し、CSS でアクティブなテーマに応じて一方だけを表示します。