如何使dartdoc包含其他文档？

Question

我想了解是否有一种方法可以在dartdoc生成的API文档中包含更多的文档。

根据包装布局约定，doc/目录中包含一个getting_started.md文件，并显示如下.

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

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

我还在dartdoc 文档中读到了关于类别的文章，其中指出：

类别：每个类别/主题的详细信息。对于要文档化的主题，请指定带有标记的标记文件:用于类别页面。可选地，将类别从源代码重命名为显示名称，并使用“name：”。如果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"]

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

有没有人知道如果可能包括额外的文档，如果可能，如何实现这一点？

Answer 1

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

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

只有在源代码中至少有一个元素被声明为该类别的成员时，类别才会呈现，因此该特性不适合此用例。