配置

Methanol 将按顺序尝试加载以下配置文件：

methanol.config.{js,mjs,cjs,ts,jsx,tsx,mts,cts}

若未发现配置文件，Methanol 将基于当前目录推断并应用默认设置。

配置结构

配置文件需导出一个函数，该函数接收构建上下文并返回配置对象。

export default ({ mode, root, HTMLRenderer }) => ({
	// config values
})

上下文参数说明：

• mode: development 或 production
• root: 项目根目录
• HTMLRenderer: refui HTML 渲染工具集（rawHTML、serialize 等）

核心配置属性

root

项目根目录，默认为当前工作目录（CWD）。

site

站点元信息（供模板使用）：

• site.name: 站点名称/标题
• site.logo: Logo 路径（字符串）或设为 false 以禁用（默认主题生效）
• site.favicon: Favicon 路径（字符串）或设为 false 以禁用（默认主题生效）
• site.base: 站点部署在子路径下时的 Base Path（例如 '/docs/'）
• site.repoBase: 指向仓库内容目录的 Base URL（默认主题会用它生成 “Edit this page” 链接）

注意：

• site.base 将被自动规范化为首尾斜杠形式（例如 docs → '/docs/'）。
• 除非显式配置 vite.base，否则 site.base 将作为 Vite 的 base 路径。
• dev（methanol dev）模式下 site.base 会被忽略并当作 /。请用 methanol build + methanol serve 验证子路径部署效果。

pagesDir

MDX/MD 源文件目录（路由根源）。默认为 pages；若 pages/ 不存在，将自动回退查找 docs。

componentsDir

JSX/TSX 组件目录。默认为 components。

若显式指定了 pagesDir 或 componentsDir（包括 CLI 参数指定），当目录不存在时将抛出错误。

publicDir

静态资源目录（映射至站点根路径，如 public/foo.png → /foo.png）。默认为 public。

Methanol 亦支持主题资源（theme.publicDir）。构建时将执行合并策略（主题资源垫底，用户资源覆盖），同名文件以用户资源为准。

执行合并操作时，临时目录将生成于 node_modules/.methanol/assets（若无 node_modules/，则生成于 {pagesDir}/.methanol/assets）。

设置 publicDir: false 可彻底禁用 Public 资源功能（包括主题资源）。

distDir

生产构建输出目录。默认为 dist。

buildDir

中间构建目录（用于 emitIntermediate）。默认为 build。

intermediateDir

中间态 HTML 输出目录（仅 build 时生效）。

emitIntermediate

布尔值。为 true 时在构建期间写入中间 HTML 到 build/。

theme

主题深度配置。详见 主题（进阶）。

关键字段：

• theme.root: 主题根目录（必填）
• theme.template: HTML 布局模板函数（接收 { ctx, page, PageContent, ExtraHead, withBase, HTMLRenderer, components }）
• theme.components: 默认 MDX 组件
• theme.componentsDir: 主题组件目录
• theme.pagesDir: 主题页面目录
• theme.publicDir: 主题 Public 资源（合并到 publicDir）
• theme.sources: 由 Methanol 解析的虚拟路径映射
• theme.mdx: 与用户 mdx 合并的默认 MDX 选项
• theme.vite: 与用户 vite 合并的默认 Vite 选项

mdx

自定义 MDX 配置函数。接收 { mode, root } 并返回配置对象。

vite

自定义 Vite 配置函数。接收 { command, mode, root, isPreview }。

preBuild / preBundle / postBundle / postBuild

构建流程扩展钩子（Hooks）。

• preBuild 在 dev 启动时与 build 前执行。
• preBundle 仅在 build 时执行：页面渲染完成后、Vite 打包之前。
• postBundle 仅在 build 时执行：Vite 打包完成后、Pagefind 建索引之前。
• postBuild 只在 build 后执行（dev 不执行）。
• 这些 hook 都可以是函数或函数数组。
• 执行流：User preBuild → Theme preBuild → Render → User preBundle → Theme preBundle → Bundle → Theme postBundle → User postBundle →（可选）Pagefind → Theme postBuild → User postBuild。

Hook 上下文：

• mode, root, command, isDev, isBuild, isPreview
• HTMLRenderer
• site（与 ctx.site 同形）
• data（可变数据对象，用于跨 Hook 共享状态）

preBundle / postBundle / postBuild 额外参数：

• pagesContext
• pages
• pagesTree
• pagesByRoute

示例：

export default () => ({
	preBuild: ({ data, site }) => {
		data.startedAt = Date.now()
		console.log('Building', site.name)
	},
	preBundle: ({ pages }) => {
		console.log('Rendered pages:', pages.length)
	},
	postBuild: ({ data, pages }) => {
		console.log('Duration (ms):', Date.now() - data.startedAt)
		console.log('Pages:', pages.length)
	}
})

pagefind

启用或配置 Pagefind 搜索。默认值：false。

pagefind: false
// or
pagefind: { enabled: true }
// or
pagefind: {
	enabled: true,
	excerptLength: 30,
	build: {
		outputSubdir: 'pagefind',
		verbose: true
	}
}

说明：

• enabled 和 build 以外的键会传给 Pagefind JS 的 options()。
• build 属性专用于构建配置。

starryNight

代码高亮配置（基于 rehype-starry-night）。默认值：false。

starryNight: false
// or
starryNight: true
// or
starryNight: {
	// options forwarded to rehype-starry-night
}

• 当 starryNight 配置为对象时，除非显式设置 enabled: false，否则视为开启。
• 页面 Frontmatter 的 starryNight 优先级最高。
• CLI 参数 --code-highlighting 可运行时切换是否启用全局代码高亮。

gfm

GitHub Flavored Markdown (GFM) 开关。默认值：true。

开启后，Methanol 将支持标准 GFM 语法特性（表格、任务列表、删除线、脚注、自动链接等）。

gfm: true
// or
gfm: false

CLI 覆盖

命令行参数优先级高于配置文件：

• --input 和 --components 覆盖 pagesDir 与 componentsDir
• --assets 覆盖 publicDir
• --output 覆盖 distDir
• --site-name 覆盖 site.name
• --base 临时覆盖 site.base（dev 模式下会被忽略）
• -v/--verbose 开启详细日志模式
• --config 指定配置文件路径
• 位置参数 input/output 分别映射至 --input/--output（dev 仅使用 input）

示例

import tailwindcss from '@tailwindcss/vite'

export default ({ mode }) => ({
	site: { name: 'My Docs' },
	theme: {
		root: '.',
		template: ({ PageContent, ExtraHead, ctx, withBase, HTMLRenderer, components }) => (
			<>
				{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>
						<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>
		}
	},
	mdx: () => ({
		development: mode !== 'production'
	}),
	vite: () => ({
		server: { port: 5173 },
		plugins: [tailwindcss()]
	})
})