It should be possible to create a complete documentation website

[wkornewald]

Is your feature request related to a problem? Please describe Dokka currently focuses on generating a reference documentation. This is already plenty useful, but it's by far not enough. People need nice guides with examples and explanation pages and maybe FAQ etc. Within those pages it's often necessary to link to reference pages for details (e.g. a certain class or function). Also, a good documentation page needs full control over the sidebar. Currently, the sidebar is auto-generated when outputting HTML and it can be grouped by module, but there is no control over the page structure and you can't even define a nice intro home page.

Basically, the HTML output format is too limiting and rigid, so the only solution is to use gfm output and then wrap that in a separate Markdown-based static site generator. However, then you can't easily link to individual classes/functions by their identifier, but instead have to link to the generated Markdown files, which requires browsing the file system because the names can't be guessed. Also, the gfm output doesn't look very nice, especially for multi-platform documentation (at least not without manual extra effort).

Finally, the gfm solution involves a non-trivial amount of effort to generate a simple HTML website.

Describe the solution you'd like Make it possible to write arbitrary pages in Markdown and integrate them into the sidebar and the generation process. Links to functions/classes should work exactly like within the module documentation or kdoc comments. It should be trivial to generate a nice-looking HTML website, complete with reference and guides and examples and a search bar with auto-complete. We really need a holistic solution that works out of the box and produces high quality output with minimal effort.

[daymxn]

FWIW, we work around this at Google by using a custom dokka plugin, although I agree that providing functionality for folks to more easily integrate dokka with simpler systems would be nice.

+1

[joffrey-bion]

This is an interesting suggestion. However, to get a very nice documentation website, you might need more than just markdown, so I'm not sure to which extent this would be useful.

In the Krossbow project, I write my documentation website using MkDocs (which is really nice), and I can still use the HTML output of Dokka as a separate link in the sidebar.

To do this, I output the Dokka-generated files into the structure of the documentation website using this in the root build.gradle.kts:

tasks.withType<org.jetbrains.dokka.gradle.DokkaMultiModuleTask>().configureEach {
    outputDirectory.set(file("$rootDir/docs/kdoc"))
}

Then, in the MkDocs yaml config, I add a sidebar element to point to the KDoc index: https://github.com/joffrey-bion/krossbow/blob/main/mkdocs.yml#L82

I can also link from regular documentation pages to the API reference generated by Dokka using relative paths like this: https://github.com/joffrey-bion/krossbow/blob/0d156eaec875c9578f7a181dd112aaa2a2681c53/docs/stomp/config.md?plain=1#L26

Of course, this is not as nice as a class/function reference, but the flexibility and features of MkDocs couldn't easily be reached by Dokka (it would be a tremendous effort which I'd rather see invested in a cleaner Gradle plugin for instance).

[wkornewald]

I don't think we need to reproduce the whole MkDocs feature set for this to be very useful. It's not an "all or nothing" and you can allow more complex customizations via Dokka plugins. My suggestion is to simply allow adding arbitrary Markdown pages and have enough control over the sidebar. From a quick glance, the Krossbow documentation seems to use just a simple set of MkDocs features, too.

BTW, the Krossbow reference looks like a completely separate website and the search results are also split up between reference and main documentation. This feature request is about having a fully integrated, single website exactly to prevent this split between two worlds. That's why our current workaround uses gfm with mkdocs.

Unfortunately, MkDocs is extremely slow when using the gfm solution. It takes a whole hour for mkdocs to process our website - and that's after running Dokka which takes an additional 25min...

[mistralaix]

Any update here? Looked into MkDocs and Writerside to have a single documentation with Dokka reference in it but doesn't seem to be the best solution

[tripayfact]

Is this in the roadmap? This is very very useful

[maxoertel]

This can actually already be reached today:

How to have guide/custom md pages in the menu

--> Add new module and include a MD file in the dokka part of the build.gradle

includes.from(
            project.layout.projectDirectory.file("src/commonMain/kotlin/Welcome/welcome.md"),
        )

• Make sure the Package is exactly called as you want the nav entry to be shown
• add next to the md file a simple Kotlin file, otherwise the package is omitted

package Welcome

internal object _KeepPackage

then add this module in your root build.gradle inside the dokka{ dependencies {..}} block dokka(project(":module"))

You can add multiple pages per module (= subpages for nav entry). To change the nav entry name just change the dokka module name moduleName.set("Welcome").

Only problem: nav entries show camel case (= packageName). To solve this inject some custom css:

For first menu item for example:

.sideMenu > .toc--part:nth-child(0) .toc--row a span{
    margin-right: 4px;
}

MD content for the main nav entries can be added by adding md file to the module: includes.from(project.layout.projectDirectory.file("docs/home/homepage.md")) // homepage