如何让 dartdoc 包含其他文档？答案

【问题标题】：How to get dartdoc to include additional documentation?如何让 dartdoc 包含其他文档？
【发布时间】：2019-10-18 04:43:59
【问题描述】：

我想了解是否有办法在dartdoc 生成的 API 文档中包含其他文档。

根据Package layout conventions 有一个getting_started.md 文件包含在doc/ 目录中，显示如下...

enchilada/
  ...
  doc/
    api/ ***
    getting_started.md

该文件如何通过dartdoc 合并到文档中，它在输出中的什么位置显示？我尝试在doc/ 目录中简单地添加我自己的*.md 文件，但它们似乎没有被使用。

我还阅读了 dartdoc documentation 中关于 Categories 的内容，其中指出：

类别：每个类别/主题的更多详细信息。对于您要记录的主题，请使用 markdown: 指定降价文件以用于类别页面。或者，将源代码中的类别重命名为带有“名称：”的显示名称。如果 dartdoc_options.yaml 中没有定义匹配的类别，则源代码中声明的类别将不可见。

然后我尝试像这样引用dartdoc_options.yaml 文件中的其他文档...

dartdoc:
  categories: 
    "Getting Started":
      markdown: doc/getting_started.md

    "Search Filters":
      markdown: doc/search_filters.md


  categoryOrder: ["Getting Started", "Search Filters"]

但这也没有产生任何结果。

有谁知道是否可以包含其他文档，如果可以，如何实现？

【问题讨论】：

你在这里找到线索了吗？我跟你情况一样

标签： dart documentation dart-pub dartdoc

【解决方案1】：

Dartdoc 不允许在 API 文档中包含任意 .md 文件。您可以在 README.md 或其他文档中创建指向它们的链接，例如通过 GitHub 或其他为他们提供服务的网址。

例如，dartdoc 包为“贡献”文档执行此操作，它显示在 API 文档中，此处为：https://pub.dev/documentation/dartdoc/3.0.0/index.html

仅当源代码中的至少一个元素被声明为该类别的成员时，类别才会呈现，因此该功能不太适合此用例。

【讨论】：