Mkdocs versioning with mike: how to publish entire branch contents not site dir

Support
, ,
1

BACKGROUND

  • Using mkdocs with mike.

  • mike runs mkdocs to create versions in subdirectories, but in a separate branch (by default gh_pages but can be any).

  • That ‘deploy’ branch is the entire website, complete with index.html (that redirects to a chosen version subdir), plus as many subdirs each with a built mkdocs site.

  • You define versions to be listed, which is the default, aliases for them (e.g. 2.9 and latest have the same content).

  • If you keep your documentation version sets in separate github branches (say, 1.0, 2.0) and run mike deploy in each branch, you will get subdirs /1.0/ and /2.0/ in your target (‘deploy’) branch.

PROBLEM

Netlify builds want to know where the built subdir is in the same branch.

But I want a build (say, for 2.0 branch) to be:

  • build command: mike deploy -b somebranch 2.0
  • publish BRANCH (not directory): somebranch

Everything in somebranch is the multi-version content for the site.

(I would have to figure out how to parameterise the version to match the updated github branch, but there is a bigger initial question.)

QUESTION

Is this possible?

ADDENDUM: WHY

mkdocs + material + mike gives a standard-tool approach to versioning and a menu to implement it on the site.

2

(Partial self answer)

Can’t build on one branch and deploy another. A workaround:

  • Do the build (run mike deploy -F config.yml) somewhere else (e.g. GitHub actions)
  • Set netlify site build command to blank
  • Set netlify site publish branch to gh-pages
  • Set netlify site publish dir to /
1 Like
3

Hey there, @PaulJacobs-percona :wave:

Thanks for writing such a stellar post, and for following up with your solution. I am glad you have found a workaround here. This type of knowledge sharing is so beneficial, and we appreciate it! :netlisparkles: