How to get dartdoc to include additional documentation?

Question

I would like to understand if there is a way for me to include additional documentation with the API docs that get generated by dartdoc.

According to the Package layout conventions there is a getting_started.md file included inside the doc/ directory and is displayed like this ...

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

How does that file get incorporated into the docs by dartdoc and where does it show up in the output? I've tried to simply add my own *.md files in the doc/ directory but they don't appear to get used.

I have also read about Categories in the dartdoc documentation which states:

categories: More details for each category/topic. For topics you'd like to document, specify the markdown file with markdown: to use for the category page. Optionally, rename the category from the source code into a display name with 'name:'. If there is no matching category defined in dartdoc_options.yaml, those declared categories in the source code will be invisible.

So I then tried to reference the additional documents in the dartdoc_options.yaml file like this ...

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

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


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

But that too did not generate any results.

Does anyone know how if it's possible to include additional documentation and if so how to accomplish this?

Answer 1

Dartdoc does not allow arbitrary .md files to be included in API documentation. You can create links to them in the README.md or other documentation, e.g. via GitHub or another web address serving them.

For example, the dartdoc package does this for the 'contributing' documentation, and it shows up in the API docs, here: https://pub.dev/documentation/dartdoc/3.0.0/index.html

Categories will only render if at least one element in the source code is declared as a member of that category, so that feature isn't well suited to this use case.