零配置 : docmd docs

docmd 具备一套智能启发式引擎，可在无需编写任何配置的情况下自动解析并构建文档结构。您无需编写一行配置即可开始构建、预览和翻译文档。

工作原理

在没有 docmd.config.json 文件的情况下运行时，引擎会自动进入 零配置模式。它扫描工作区目录中的内容并应用以下启发式规则：

引擎按顺序在这些候选目录中查找文档文件：

如果找到某个候选目录且其中包含 Markdown 文件，则将其选为源目录。若未找到任何目录，但项目根目录中存在 Markdown 文件，则使用根目录（自动忽略 node_modules、.git，以及 site/、dist/、out/ 等输出文件夹）。

若完全没有找到文档内容，docmd 会自动初始化一份全新的入门结构。

引擎扫描目录结构以动态提取版本与本地化元数据：

如果不存在顶层版本或语言目录，引擎会通过分析文件结构动态构建导航树：

要充分发挥零配置模式的优势，请遵循以下结构建议：

一份 docmd.config.json（或不提供任何配置）即可开箱即用地获得一个可用的站点。以下键附带合理的默认值，只有在您希望使用不同值时才需要显式设置。

如何退出默认值

将键设为 false（或相应的空值）即可关闭某个默认值。例如 pageNavigation: false 会移除上/下页链接；theme.appearance: "dark" 会覆盖色彩模式。

键	默认值	说明
`pageNavigation`	`true`	每篇文章底部的上/下页链接
`copyCode`	`true`	`<pre>` 代码块上的复制按钮
`autoTitleFromH1`	`true`	当 frontmatter 缺失时，使用首个 `# H1` 作为页面标题

键	默认值	说明
`layout.spa`	`true`	页面间启用 SPA 导航
`layout.breadcrumbs`	`true`	页头上方显示面包屑行
`layout.header.enabled`	`true`	顶部页头
`layout.sidebar.collapsible`	`true`	桌面端侧边栏可折叠
`layout.sidebar.defaultCollapsed`	`false`	侧边栏默认展开
`layout.optionsMenu.position`	`"header"`	选项菜单（搜索 / 主题切换 / 赞助）位于页头
`layout.optionsMenu.components.search`	`true`	菜单中显示搜索触发器
`layout.optionsMenu.components.themeSwitch`	`true`	菜单中显示亮/暗模式切换
`layout.optionsMenu.components.sponsor`	`null`	按需启用 —— 设置为 URL 即可开启

键	默认值	说明
`theme.name`	`"default"`	基础 CSS 主题；预留值：`default`、`sky`、`ruby`、`retro`。任何其他值会被自动提升为模板名。
`theme.appearance`	`"system"`	默认色彩模式（跟随 `prefers-color-scheme`）。若需强制，请设为 `"light"` 或 `"dark"`。
`theme.codeHighlight`	`true`	`<pre>` 块启用语法高亮

键	默认值	说明
`cookie`	`null`	可选的 Cookie 同意对话框 —— 请参阅 Cookie 同意
`layout.banner`	`null`	可选的全站公告横幅 —— 请参阅站点横幅
`theme.template`	`null`	可选的模板选择 —— 请参阅模板

这些默认值的设定目标是让全新站点在没有任何配置的情况下也能立即可用。较旧的配置文件会保留其显式值 —— 只有未定义的键才会被填充。