テーマ実装ガイド

本ガイドでは、カスタムテーマ（レイアウト、コンポーネント、および任意のテーマページやアセット）の実装手順を詳しく解説します。ナビゲーション、目次、前後ページへのリンク、言語スイッチャー、特殊用途ページの処理など、標準的なテーマに求められる機能を網羅的に構築します。

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

推奨される構成は以下の通りです。

theme/
  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
	}
})

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

theme/index.js で、テーマの各リソースパスを定義します。

import PageTemplate from './page.jsx'

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

テンプレートのインターフェース仕様（Template Contract）

theme.template 関数には、レンダリングに必要な以下のプロパティが渡されます。

ctx: 現在のページおよびサイト全体のコンテキスト。
page: ctx.page へのエイリアス。
PageContent: ページ本文をレンダリングするコンポーネント。
ExtraHead: <head> セクションに注入される動的なコンテンツ（ランタイム、アセット、ページ固有のメタタグなど）。
withBase: Base Path を考慮した URL 生成ヘルパー（ctx.withBase と同等）。
components: テーマ標準とユーザー定義がマージされたコンポーネントセット。
HTMLRenderer: rEFui のレンダリングユーティリティ。

最小構成のテンプレート例:

import { HTMLRenderer } from 'methanol'

export default ({ PageContent, ExtraHead, ctx }) => (
	<>
		{HTMLRenderer.rawHTML`<!doctype html>`}
		<html lang="en">
			<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>
	</>
)

実際のテーマ開発では、ここになナビゲーションや目次などの要素を追加していきます。詳細は各ガイドを参照してください。