Make prefix configurable through mkdocs.yaml plugins

[xakraz]

Hi @jimporter !

Thank your for mike, I am using its integration in mkdocs-material and it's great !

AFAIU, mike works by creating / building the documentation and committing it directly to a Git branch (defaults to gh-pages).

In our company we use mkdocs to create our internal documentation. GitHub pages do not support "private" access and we used to build containers with the built documentation, setup behind an IdentityAwareProxy.

We are thinking about a workflow that would look like:

• Merge to main branch a documentation update
• CI kicks in and runs mike deploy to push the managed versioned doc to a dedicated custom branch
• CI kicks in again, triggered by this "release" branch,
  • builds a container,
  • pushes it to a registry
  • updates some deployment manifests that are also pushed back to GitHub
• CD kicks in, triggered by the deployment repo, and deployments happen.

To be able to do so, we are using the flag --branch and --prefix in all our command using mike.

Would it be possible to set these up in mkdocs.yaml to ease the usage ?

[jimporter]

--branch is already pulled from mkdocs.yml if it's set. The property is called remote_branch.

--prefix could theoretically be set in mkdocs.yml too, but I primarily wrote mike to be used by other tools (such as CI), so I preferred options to be specified on the command line as I find it more obvious; that's where you have to pass the version number/aliases, after all. I'd have to think about whether I want to support setting that option in multiple ways. Moving more stuff to mkdocs.yml might make sense though, since I'd like to remove the set-default command for v2.0 and have that be managed by the mike MkDocs plugin.

[xakraz]

Thanks for your reply @jimporter.

I understand your point regarding the "obviousness" of an option. in the end, the value is "written", either in mkdocs.yaml either in the CI system config.

Having both capabilities would be great 😃 !

[jimporter]

I think I've convinced myself that adding prefix to mkdocs.yml (somewhere) makes sense. Since there are multiple commands, and some of them get used by the end-user (e.g. set-default, delete, alias), having to remember to set the prefix via command-line could get irritating.

[xakraz]

These are exactly the use cases that led me to open this issue :)

[jimporter]

This is now supported via the plugins.mkdocs.deploy_prefix config property.