主题实现指南
本指南将引导开发者构建自定义主题（涵盖布局、组件、可选主题页面及资源），并完善导航、目录、前后页、语言切换及特殊页面处理等核心框架功能。
推荐目录结构
建议结构：
theme/
index.js # 导出主题对象
page.jsx # 模板组件（Layout）
components/ # 默认 MDX 组件（可选）
pages/ # 主题自带页面（可选）
public/ # 主题 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>的额外内容（Methanol 运行时、页面资源、页面<Head>输出等）withBase：URL Base 处理函数（与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>
</>
)
在实际主题开发中，通常需集成导航、目录及页面信息等模块。各功能实现详解如下：