主题实现指南

本指南将详细介绍如何构建符合 Methanol 架构的自定义主题。你将学习如何实现导航、目录、多语言支持等文档站点的核心功能。

配置启用主题

在 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 的包。
本地路径： 解析为指向文件或目录的直接路径。

使用已发布的主题

通过 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="zh">
			<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>
	</>
)

关于实际主题开发中的详细实现，请参阅以下专项指南：