DocFx custom navigation

Question

The default navigation in DocFx uses namespaces. So it looks like this:

- MyNamespace.SomeArea
  - Class 1
  - Class 2
- MyNamespace.SomeOtherArea
  - Class 3
  - Class 4

However, we need to have the navigation tree using the actual folders of classes which don't correspond with the namespace.

So it would looke like this

- RootFolder/Subfolder1
  - Class 1
- RootFolder/Subfolder2
  - Class 2
  - Class 3
  - Class 4

I haven't found a way how to set this in DocFx.

However we could generate api/toc.yml ourselves and feed it to DocFx, but it is even possible? DocFx always creates its own api/toc.yml

Answer 1

I am not an expert in DocFX so I can't tell if there is a solution to modify DocFX behaviourto suit your needs. However there is a possible workaround.

1. Run docfx metadata: This will generate the metadata for your project (i.e. all the files contained in the api/ folder). To control the behavior of this command, use the metadata section in the docfx.json setting file. See here for available items.
2. Replace the api/toc.yml created automatically by yours.
3. Run docfx build: This will generate the static website (usually in _site/) from the API files (usually in api/), the articles (usually in articles/), and the overwrite files (usually in apidoc/). To customise this step see here.

Then the difficult question is how to generate your costum toc.yml. I would probably use a bash script to do so. In one of my projects, I used bash scripts to recursively create toc.yml file for my documentation articles.