テーマ実装ガイド

本ガイドでは、Methanol のアーキテクチャに準拠したカスタムテーマの実装手順を詳しく解説します。ナビゲーション、目次、多言語対応など、ドキュメントサイトに求められる主要な機能の実装方法を学ぶことができます。

標準的なディレクトリ構成

推奨されるテーマのディレクトリ構成は以下の通りです。

index.js: テーマオブジェクトのエントリポイント
page.jsx: メインのレイアウトテンプレート
components/: デフォルトの MDX コンポーネント（任意）
pages/: テーマ同梱のページ（任意）
public/: テーマ専用の静的アセット（任意）
sources/: theme.sources でマッピングするリソース（任意）

テーマの設定方法

カスタムテーマを有効にするには、methanol.config.js でテーマのルートディレクトリとテンプレートコンポーネントを指定します。

import PageTemplate from './theme/page.jsx'

export default () => ({
	theme: {
		root: './theme',
		template: PageTemplate
	}
})

テーマオブジェクトの定義

テーマは、エントリポイント（index.js）でオブジェクトとして定義することも可能です。これは再配布可能なテーマを作成する場合に特に有効です。

import PageTemplate from './page.jsx'

export default () => ({
	theme: {
		root: '.',
		template: PageTemplate,
		componentsDir: './components',
		pagesDir: './pages',
		publicDir: './public',
		sources: {
			'/theme': './sources'
		}
	}
})

公開と解決の仕組み

テーマは methanol-theme-xxx という名前の npm パッケージとして公開できます。Methanol は以下の優先順位でテーマを解決します。

標準搭載テーマ: 内蔵のプリセット（default、blog など）
パッケージ解決: methanol-theme-xxx という名前のパッケージを検索

ローカルテーマ（プロジェクト内のファイル）を使う場合は、設定ファイルで import して theme に渡してください。

公開済みテーマの使用方法

CLI の場合:

methanol build --theme xxx

methanol.config.js の場合:

export default () => ({
	theme: 'xxx'
})

テンプレートの仕様

theme.template 関数は、以下のプロパティを含むコンテキストオブジェクトを受け取ります。

ctx: サイトおよびページのコンテキスト
page: ctx.page へのエイリアス
PageContent: ページ本文をレンダリングするコンポーネント
ExtraHead: ランタイムスクリプト、スタイル、およびページ固有の <Head> コンテンツを注入
withBase: ベースパスを考慮した URL 生成ヘルパー
components: テーマ標準とユーザー定義がマージされたコンポーネントセット
HTMLRenderer: rEFui のレンダリングユーティリティ

最小構成の実装例

import { HTMLRenderer } from 'methanol'

export default ({ PageContent, ExtraHead, ctx }) => (
	<>
		{HTMLRenderer.rawHTML`<!doctype html>`}
		<html lang="ja">
			<head>
				<meta charset="UTF-8" />
				<meta name="viewport" content="width=device-width" />
				<ExtraHead />
				<title>{ctx.page.title || ctx.site.name}</title>
			</head>
			<body>
				<PageContent />
			</body>
		</html>
	</>
)

実際のテーマ開発における詳細な実装については、以下のガイドを参照してください。