How to get dartdoc to include additional documentation?

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?

Solution

I disagree - arbitary .md is well catered for and I use an md file as the top level explainer for each of the libs I need to document.

There are 'gotchas' though and as others have pointed out:

your method/function docstring should include an @category statement for the topic categories you intend
your options.yaml should include the category, and their order
you need both the category in the docstring AND the matching reference in the .yaml or one or the other will be ignored
you need a matching .md file (I place mine in a docs folder)

Then you will have something like this in your yaml:

dartdoc:
  categories:
    "Getting Started":
      markdown: docs/install.md
      name: install
    "Authorization":
      markdown: docs/auth.md
      name: authorization
    
  categoryOrder: ["Getting Started", "Authorization"]

and your method/function will have this docstring:

/// {@category Authorization}

don't forget to create the .md file too.