主题

主题全权掌控布局（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.root 必填项，指定主题路径的基准目录。

默认值与校验

componentsDir / pagesDir / publicDir 支持三种配置模式：
- 省略：默认映射至主题根目录下的 ./components / ./pages / ./public（若目录不存在则自动跳过）
- 设置为 false：显式禁用该功能
- 显式路径字符串：指定特定目录（若目录不存在将抛出错误）

模板接口规范

theme.template 接收以下参数：

PageContent: 渲染当前页面内容的 JSX 组件
ExtraHead: 需注入 <head> 的额外内容（包含页面资源、Methanol 运行时及页面自定义 <Head>/head 内容）
ctx: 页面与站点上下文（ctx.page, ctx.pages, ctx.pagesTree, ctx.pagesByRoute, ctx.languages, ctx.language, ctx.site, ctx.withBase）
page: ctx.page 别名
withBase: URL Base 处理函数（等同于 ctx.withBase）
HTMLRenderer: refui HTML 渲染器（提供 rawHTML 与 serialize 方法，或用于手动渲染 JSX 组件）
components: 合并后的组件集合（包括主题组件与用户自定义组件）

函数需返回一个完整的 JSX 树。

**重要：**务必将 <ExtraHead /> 置于 <head> 标签内，否则页面 <Head>/head 及自动注入资源将无法生效。

当站点部署于子路径（site.base !== '/'）时：

对于需遵循 Vite base 的 URL（如 Vite 管理的运行时资源），请使用 withBase('/...')（或 ctx.withBase('/...')）。
通常无需对 theme.sources URL 或 public/ 静态文件使用 withBase()（Methanol 会在构建时进行解析）。但在 JS 中动态生成 URL 时若遇 Vite dev 路径解析不一致，withBase() 仍是有效的解决方案。

主题默认组件

theme.components 定义主题默认 MDX 组件。用户 components/ 目录下的同名组件将覆盖主题组件。

模板亦会接收 components 对象（便于在布局中调用，如导航、搜索组件等）。

主题预设页面机制

主题页面遵循与用户页面一致的路由规则。用户页面始终拥有更高优先级。

主题提供的 /404 页面仅在用户未定义 404 页面时生效。

主题静态资源合并

若主题配置了 publicDir，其内容将在 dev/build 启动时复制至用户 public 目录。即使用户已配置 publicDir，主题资源仍会被复制，同名文件将自动跳过。若用户侧未创建 public 目录，则直接使用主题的 public 目录。

主题资源映射

theme.sources 将虚拟 URL 映射至物理文件。该机制由 Methanol 解析器处理，而非 Vite alias。

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

构建钩子（Hooks）

主题亦可提供构建钩子（结构与用户配置 hook 一致）：

preBuild（dev 启动及 build 流程开始前）
preBundle（页面渲染完成之后、Vite 打包开始之前）
postBundle（Vite 打包完成之后、Pagefind 执行之前）
postBuild（整个构建流程结束后）

主题