问题

随着软件产品的成熟，其文档自然会不断扩展。当一个项目增长到数百或数千个 Markdown 文件时，许多文档生成器都会面临构建时间缓慢、开发服务器热重载滞后以及导航结构让维护者和用户都感到不知所措的问题。

为什么重要

如果文档生成需要几分钟而不是几秒钟，作者就会失去进行细微修改的动力，从而导致内容陈旧且不准确。对于用户来说，庞大且杂乱无章的侧边栏菜单会使查找信息变得非常沮丧，导致支持工单增加，开发者体验下降。

方法

docmd 专为速度和可扩展性而设计。通过利用高性能的解析引擎和颗粒化的基于文件的构建策略，它可以在几秒钟内处理数千个页面。其优化的 SPA（单页应用）交付确保了用户在大型网站中的导航依然是瞬时完成的。

实施

1. 颗粒化的项目结构

避免将所有文件放在一个扁平的目录中。使用与您的产品架构相匹配的深层嵌套文件夹结构。这使得项目更易于维护，并允许 docmd 在开发期间高效地跟踪更改。

2. 优化的搜索索引

对于大型网站，搜索插件 至关重要。docmd 生成高度压缩的搜索索引，并按需加载。这确保了即使有数千个页面，初始页面加载速度依然很快，同时在整个网站范围内提供全文搜索能力。

3. 版本控制和归档

利用 版本控制引擎 将旧版内容与当前文档分开。通过将旧版本隔离到各自的构建上下文中，可以减少日常更新中需要重新处理的页面数量，从而显著提高开发速度。

// docmd.config.js
export default {
  versions: {
    current: 'v3',
    all: [
      { id: 'v3', dir: 'docs/current', label: 'v3.x (最新)' },
      { id: 'v2', dir: 'docs/v2',      label: 'v2.x (旧版)' }
    ]
  }
};

4. 基于组件的导航

使用 navigation.json 文件将您的导航分解为逻辑片段。这允许您为网站的不同部分定义独特的侧边栏层级，防止主导航变得杂乱无章。

权衡

大型网站在构建过程中自然会消耗更多的磁盘空间和内存。为了在极端规模（10,000+ 页面）下保持亚秒级的构建时间，请考虑使用配备 SSD 存储和充足 RAM 的高性能 CI/CD 环境，以处理文件的并行处理。