I'm trying to create a seamless version switch experience with an MkDocs- and Dokka-generated site. ...

# dokka

[Oliver.O]

I'm trying to create a seamless version switch experience with an MkDocs- and Dokka-generated site. I'm creating the whole static site locally without any strange "gh-pages" branch tweaking.

With MkDocs it's easy, I can just create the versions file and version directories and the version dropdown will just be there, even from older versions to newer ones. With Dokka, it seems like I can only go backwards, because all "older" versions are hardwired at creation time, and newer versions won't be seen as they arrive. Is my understanding correct?

[hfhbd]

It depends on your setup. How do you keep the old versions?

[Oliver.O]

In one directory as described here:

dokka {
    pluginsConfiguration {
        versioning {
            version = newApiVersion
            versionsOrdering = listOf(newApiVersion) + previousVersions
            olderVersionsDir = apiVersionsDirectory
        }
    }
}

[hfhbd]

So you checkin your (old) apis? Ktor does the same and you can visit all different versions https://api.ktor.io/index.html

[hfhbd]

Or I don’t understand your problem.

[Oliver.O]

Yes, the old APIs land in git. But seemingly the versions (current and old ones) are hardwired into Dokka-generated HTML/JS. Don't know how Ktor folks did it.

[Oliver.O]

Seems like they regenerate everything: https://github.com/ktorio/api.ktor.io/blob/main/build_doc.sh

[CLOVIS]

Alternative solution: put the dokka output in the MavenCentral JAR and let <http://javadoc.io|javadoc.io> deal with versioning.

[Oliver.O]

Interesting. Does it have to be in the javadoc format or do they support Dokka HTML as well?

[CLOVIS]

The only thing that matters is that it's HTML. https://javadoc.io/doc/dev.opensavvy.prepared/compat-parameterize/latest/index.html

[CLOVIS]

If you want to use it:
• Each time you create a new Maven artifact you need to navigate to it once to register it (or any of your users can do it too)
• After that, it checks for new versions automatically every few days
• The main page, https://javadoc.io lets you find out the URLs & generate badges
The author has helped me in the past fix a link issue in the Dokka format, so he's not opposed to it

[Oliver.O]

Is javadoc.io a new project? Tried with compat-parameterize, switched to 2.1.0, then it took quite a while to load (showing just a blank page), then it rendered an unstyled page without the navigation on the left.

[CLOVIS]

No, it's been here for years, but my javadoc setup was broken for a few versions 😕