I need to be able to version my projects (mike and projects plugin compatibility)

[PhilStollery]

Hi,

I'm working on a programme that is developing a suite of products/services. Our documentation can't be versioned at the programme level, I need to be able to have different versions for each product.

I've installed (and became an insider) the projects plugin and thought all I need to do is use mike in each subproject site. Is that right?

To complicate things, it's a government project so it's hosted on a private GitLab repo - so all the CI/CD is not GitHub. The current build pipeline works, but adding mike into it might be a problem?

Once I've proved it all hangs together, I'll be going to finance to ask for an enterprise licence. But want to know if it'll work before then.

[niclasheinz]

Hello @PhilStollery

I believe that this configuration will not work as expected. The problem is that Mike was primarily developed for GitHub Pages, which by default uses the “gh-pages” branch as a source. GitLab Pages works fundamentally different and uses a different workflow for publishing documentation.

After several tests and different approaches, I could not successfully integrate Mike into GitLab.

I did some research on the internet and it seems that there is no alternative that works in GitLab - unfortunately.

[PhilStollery]

I'm using GitLab pages at the moment - but have a rather complex pipeline as we build and deploy to Kubernetes. Maybe I can reverse engineer the versions.json file?

[niclasheinz]

I think the real problem is that Mike can't save the documentation and its versions in a Gitlab-friendly location. Since Mike can't save anything, the version always stays the same (only the last day is shown, nothing else). In my case, the version.json doesn't help, and I've noticed that with gitlab, all versions of a documentation are the same version, but show up as 1.4 and 1.5. I thought about creating a tar file, moving it to a bucket and retrieving it when a new deployment job starts. But that is very cumbersome and not production friendly. I haven't tested it, but maybe it works. I can't think of any other possibility.

[niclasheinz]

Sorry for the noise.

Maybe this https://stackoverflow.com/questions/72467521/auto-deploy-mkdocs-with-versionning-using-mike-on-gitlab-pages can help you! completely overlooked it

laurels goes to @alexvoss

[PhilStollery]

I think I need to clarify - we can ignore GitLab for now. On my docs site, how can I have a different version drop down for each project? (Using the insiders projects plugin).

So I need one mkdocs site, that has docs for all our individual products, each product has their own version number and versions of their docs.

[niclasheinz]

Unfortunately, I can't say whether this will work or not - I haven't worked with the projects plugin yet. You can try it by initialising a new repo, building the project structure according to https://squidfunk.github.io/mkdocs-material/plugins/projects/ and enabling mike, or perhaps someone in the community can help.