零配置 (Zero-Config)
docmd 拥有智能的启发式引擎,旨在自动解析和结构化你的文档。你可以直接开始编写、预览和翻译你的文档,而无需编写任何配置。
工作原理
在没有 docmd.config.json 文件的情况下运行时,引擎会自动触发 零配置模式 (Zero-Config Mode)。它会扫描工作区目录以查找内容并应用以下启发式规则:
1. 源目录检测
引擎会按顺序在以下候选目录中寻找文档文件:
docs/src/docs/documentation/content/.(根目录回退)
如果找到其中一个候选目录且包含 Markdown 文件,它就会被选为源目录。如果没有找到候选目录,但项目根目录下有 Markdown 文件,则直接使用根目录(自动忽略 node_modules、.git 以及输出文件夹如 site/、dist/ 和 out/)。
如果完全没有找到文档内容,docmd 会自动初始化一个全新的默认脚手架结构。
2. 版本与语言环境启发式
引擎会扫描文件夹结构以动态提取版本控制和本地化元数据:
- 版本:匹配
v[0-9]+(例如v1.0,v08)的子目录被解析为文档版本。 - 语言环境:具有两位字母语言代码(例如
en,de,zh)的子目录被视为本地化变体。 - 结构提取:最高版本被指定为当前版本,找到的第一个语言环境(如果存在,优先考虑
en)被设置为默认语言。
3. 自动导航路由
如果根目录没有版本或语言环境目录,引擎会通过分析文件结构动态构建导航树:
- 子目录映射为导航分组。
- 标题根据文件名动态生成。例如,
getting-started.md会被格式化为Getting Started。 - 索引文件(
index.md,README.md)被路由为当前目录的落地页。
零配置最佳实践
为了充分利用零配置模式,建议遵循以下结构规范:
- 明确的文件命名:使用清晰的、以连字符或驼峰式命名的文件名。自动加载器会将其转换为易读的标题。
- 基于文件夹的分组:将相关文档放入子文件夹中,以在侧边栏中自动分组。
- 索引回退:始终在源文件夹的根目录下放置
index.md或README.md,以用作落地页。 - 干净的输出路径:如果你使用根目录
.作为源目录,请将构建产物保留在默认的site/文件夹中,该文件夹会被自动忽略。