模仿go_router配置dartdoc却无法显示额外文档？

go_router包的文档页面左侧侧边栏能显示额外文档作为主题，我参考了它的dartdoc_options.yaml配置文件，也阅读了dartdoc的高级特性文档，但我的fluttery_framework包的文档页面却没显示这些主题。

本地执行dart doc .生成了预期的doc/api目录，但categories.json文件内容是空数组[]，说明dartdoc没识别到我定义的分类。我注意到dartdoc文档里提到：‘若dartdoc_options.yaml中无匹配分类，源码中声明的分类会不可见’，但go_router并没有做此类标记却能正常工作，请问我遗漏了什么？

1. 核对dartdoc_options.yaml的配置细节 #

go_router的配置核心是直接指定了额外markdown文档的路径，而非依赖源码标记。你需要确保自己的配置里正确映射了文档路径，示例格式如下：

dartdoc:
  categories:
    "使用指南":
      markdown:
        - doc/guides/*.md
    "代码示例":
      markdown:
        - doc/examples/*.md
  categoryOrder: ["使用指南", "代码示例"]

注意路径要和你项目中额外文档的实际存放位置完全对应，dartdoc会扫描指定路径下的markdown文件生成侧边栏主题。

2. 检查额外文档的命名与路径规范 #

dartdoc对额外文档有隐性要求：

• 文件名建议用小写字母加连字符（比如getting-started.md），避免特殊字符
• 确保markdown文件存放在项目根目录的指定子目录下（比如doc/guides/），且未被.gitignore或dartdoc的忽略规则排除

3. 确认dartdoc版本兼容性 #

不同版本的dartdoc对配置的解析逻辑可能有差异，先执行dart doc --version查看本地版本，尝试升级到最新稳定版：

dart pub global activate dartdoc

升级后重新执行dart doc .，再检查categories.json是否生成了正确内容。

4. 澄清dartdoc文档的描述误区 #

你看到的那段文档描述，针对的是源码中用@category标记的代码元素分类，而非额外markdown文档的独立主题。go_router属于后者——它完全通过配置加载外部markdown生成侧边栏，不需要在源码里加任何分类标记，这就是它能正常工作的原因。

5. 区分本地与pub.dev的差异 #

如果本地生成的文档侧边栏能正常显示主题，但pub.dev上不显示，大概率是pub.dev的构建缓存或dartdoc版本问题。可以尝试重新发布包时清理本地缓存，或者等待pub.dev的文档更新机制触发重新构建。

内容的提问来源于stack exchange，提问作者Drawn