documenting troubleshooting mike versioning + github pages + mkdocs material

[shane0]

troubleshooting mkdocs material + mike + github pages

• discuss https://github.com/squidfunk/mkdocs-material/discussions/6521
• the instructions in the documentation are very confusing and do not work, lets fix that
• mike build clarify why this does not exist?
• mike serve clarify why this replaces mkdocs serve and why
• github pages deployments cannot find versions.json and do not display the version dropdown
• reproduced here: https://shanenull.com/buddhism_research/
• https://github.com/squidfunk/mkdocs-material/issues/3164
• finding lots of discussions and threads and bugs surrounding this
• a new pay to use projects feature is being developed which reduces incentive to document or fix this

[shane0]

https://github.com/squidfunk/mkdocs-material/discussions/6521

[shane0]

https://github.com/jimporter/mike/issues/185

[shane0]

Error with Permissions-Policy header: Origin trial controlled feature not enabled: 'interest-cohort'.

[shane0]

what is weird?

example

• https://github.com/squidfunk/mkdocs-material-example-versioning
• this is not a repo with a working configuration to use
• this is just the converted html
• it has a commit to fix the notification of latest version
• mike overlaps mkdocs and that is not clear
• you do not use mkdocs serve you must use mike serve this has confused many people
• you do not use mkdocs build or mike build you use mike deploy but what exactly does this do?
• when i run mike list where is it finding this configuration?
• what is the need for aliases? where are those configs stored? are aliases required? in my scenario I just want 2023/2024/...
• what does mkdocs gh-deploy do that is causing the versioning to get lost?
• is the github actions rebuilding using mkdocs build
• why is versions.json getting a 404 and is this the real problem?

[shane0]