テーマ

テーマは、HTML レイアウト（テンプレート）、デフォルトの MDX コンポーネント、およびテーマ専用のページやアセットを包括的に制御します。実装の詳細については、Methanol リポジトリに同梱されているデフォルトテーマが最適なリファレンスとなります。

テーマ実装ガイド

テーマオブジェクトの構造

export default () => ({
	theme: {
		root: './theme',
		componentsDir: './components',
		pagesDir: './pages',
		publicDir: './public',
		sources: {
			'/theme': './sources'
		},
		template: ({ PageContent, ExtraHead, ctx, page, withBase, HTMLRenderer, components }) => (
			<>
				{HTMLRenderer.rawHTML`<!doctype html>`}
				<html lang="en">
					<head>
						<meta charset="UTF-8" />
						<meta name="viewport" content="width=device-width" />
						<ExtraHead />
						<title>{page.title || ctx.site.name}</title>
						<link rel="icon" href="/favicon.png" />
					</head>
					<body>
						{components.Callout ? <components.Callout>Hi</components.Callout> : null}
						<PageContent />
					</body>
				</html>
			</>
		),
		components: {
			Callout: ({ children }) => <div class="callout">{children}</div>
		}
	}
})

必須設定

デフォルト値とバリデーション

推奨されるテーマ構成

theme/
  index.js          # テーマ定義のエントリポイント
  page.jsx          # レイアウトテンプレート
  components/       # テーマ標準の MDX コンポーネント
  pages/            # テーマ同梱の特殊ページ（任意）
  public/           # テーマ専用の静的アセット（任意）
  sources/          # theme.sources でマッピングするリソース

テーマ内の public/ は、ビルド時にプロジェクト側の publicDir と統合されます。同一パスにファイルが存在する場合は、プロジェクト側のファイルが優先的に適用されます。

テンプレートのインターフェース仕様

theme.template 関数には、以下のプロパティを含むオブジェクトが渡されます。

戻り値として、ページ全体を構成する JSX ツリーを返してください。

重要: <head> タグ内に必ず <ExtraHead /> を含めてください。これが欠落すると、自動アセットの注入やページ固有の <Head> 設定が正しく機能しません。

サブパス（site.base !== '/'）で配信する場合の注意点:

テーマコンポーネント

theme.components で定義されたコンポーネントは、MDX 内で標準的に利用可能となります。ユーザープロジェクトの components/ 内に同名のコンポーネントが存在する場合は、ユーザー側が優先されます。

テーマページ

テーマ側で定義されたページは、ユーザーページと同様のルーティングルールに従います。ルーティングが重複した場合は、常にユーザー側のページが優先されます。テーマの /404 ページは、ユーザープロジェクト内に 404 ページが存在しない場合にのみ適用されます。

静的アセットの統合

テーマに publicDir が設定されている場合、ビルドプロセスの開始時にユーザーの public ディレクトリへと統合されます。同名のファイルが存在する場合はコピーがスキップされ、プロジェクト側のファイルが維持されます。

仮想パスのマッピング (theme.sources)

theme.sources を使用して、仮想 URL を特定の物理ファイルにマッピングできます。これは Vite のエイリアス機能ではなく、Methanol 独自の解決エンジンによって処理されます。

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

テーマ固有のビルドフック

テーマ側でも、ビルドプロセスに介入するためのフックを定義できます（ユーザー設定と同様の形式）。