search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
534 stars 47 forks source link

Enable Mike in selected paths #61

Closed barreeeiroo closed 3 years ago

barreeeiroo commented 3 years ago

As title says, is it possible to just enable mike versioning in just a few paths? I am currently using material-mkdocs with tabs enabled, and we would like to enable versioning in just some tabs (a tab is defined as the first level of the hierarchy).

jimporter commented 3 years ago

Unfortunately, no. mike is fundamentally built on the idea that each version of the docs is fully independent, so it would take quite a bit of effort to get it working in a situation like you mention. Some bits could probably carry over (e.g. the versions.json format and some of the Git repo management), but I think what you're looking for is a totally different project.

The closest you could get with mike would be to have two independent mkdocs sites: one for your version-agnostic content and one for version-specific content. Then you could link between them. That would probably require some careful thought about how to handle the table of contents for the site though.

squidfunk commented 2 years ago

I would like to raise a feature request for this, too, because some documentation sites contain a mix of versioned content and evergreen content, e.g. reference docs that should be versioned + blog content, which shouldn't. If that's out-of-scope as you wrote, is there maybe a plugin that you know of which helps to combine MkDocs sites?

jimporter commented 2 years ago

The best you can do would be to put the docs from mike in a subdirectory of your gh-pages branch via mike deploy --prefix=foobar. Then, the root directory of the branch is (mostly) available to use for non-versioned pages. These are effectively different sites as mentioned above, but cross-linking should be straightforward.

If you want a unified table of contents, that's significantly harder, but I'm not sure there's a good solution for that design-wise anyway. It's not conceptually difficult to add unversioned TOC items to the versioned pages, but the reverse is less-easy: should the unversioned pages include the TOC items of the latest versioned pages? That could get confusing if you go from an older version's page to the unversioned docs. Now the versioned TOC items take you to the latest version. As such, I'd recommend leaving the TOCs alone and just adding links as appropriate in the main text.

However, it should be possible for other plugins or themes to build unversioned docs that know where the versioned ones live and then consult the versions.json file to put a version selector on the unversioned pages that takes you to the appropriate versioned pages. All that really requires is a config option to tell the unversioned docs which subdirectory the versioned docs are in.

squidfunk commented 2 years ago

Thanks for the explanation. Definitely some promising directions I'm going to explore 😊 Merry Christmas!