is it possible to add custom entries to the naviga...

# dokka

[Aaron Todd]

is it possible to add custom entries to the navigation based on markdown? e.g. by default dokka adds an entry for each module, would be useful to be able to insert an entry in to the nav list that is based on markdown content (e.g. for high level API documentation, samples, etc)

Left Nav       |
-----------------------------------------------
module-1     v |       // normal docs generated from sources
   pkg1        |
   pkg2        |
module-2     v |
   pkg3        |
   pkg4        |
...
custom       v |        // based on markdown file(s)
   subpage1    |
   subpage2    |

bonus points if we could link to these pages from API content

To clarify, I'm mostly wondering how to do this as a custom plugin, I wouldn't expect this to be supported as a general feature maintained by dokka developers (unless you think it's useful)

[Kamil Doległo]

You can just add a page to the Page graph and the corresponding entry in the nav should be created automatically

[Aaron Todd]

Thanks @Kamil Doległo , could you maybe point me to where in the plugin this should happen / easiest way to do it? How would you create a nested relationship?

[Kamil Doległo]

Well, that kind of depends on your use-case, however just adding a page with the PageTransformer should be the easiest way to do so. In the invoke method of the transformer you get the whole Page tree, so just add a node (or nodes) to it. I’ve just checked the NavigationDataProvider and if the added nodes implement the ContentPage interface, they should be parsed correctly with their child nodes

[Aaron Todd]

Ok thanks, I'll take a look into that!

[Aaron Todd]

The use case is to add supplemental documentation (e.g. maybe an introduction to using the API/library, examples, etc). I don't necessarily want all of it to be on the same root level page concatenated together (which is what happens when you do

includes.from(markdownFile1, markdownFile2)

We may also want to link to parts of this supplemental documentation from the generated API docs

[Kamil Doległo]

So then a Page transformer seems like a perfect way to do it 👍. The other would be to create a custom DocumentableToPageTranslator , I advise against it however, since transformers are easily composable and translators are not composable at all

[Aaron Todd]

Ohh follow up question I've been wondering about...In a MM project, what's the easiest way to detect you are working with the root page node? IIRC the page transformer gets called multiple times for subprojects. Or does it matter?

[Kamil Doległo]

Oh, sorry, missed the part where this is a multi-module project. In that case you should add a custom Page via the allModulesPageTransformer (in the AllModulesPagePlugin plugin)

[Aaron Todd]

Ok great, thanks! This seems like enough to be dangerous and go explore further

[Kamil Doległo]

I wonder about the navigation though. It should be constructed correctly, but may be handled separately by the templating plugin, not sure right now. Let me check. Also cc @Marcin Aman since he was working on that a while ago

[Marcin Aman]

I am not sure tbh 😄 but imho it might require you to add a separate navigation file just like we do for kotlin modules so that they can be appended.
Another work-around would be to go hackerman mode and query AddToNavigationCommandHandler and insert whatever html you want there.

[Marcin Aman]

I guess this bring up the point that API for such changes is not perfect, so if you have any thoughts on how to improve it please fill and issue or submit a PR 😄