IXP Manager uses MkDocs with Material to power its professional documentation site at https://docs.ixpmanager.org/, which is hosted via GitHub pages. This all sounds convoluted, but when set up, it’s really simple, and we have this documented here.
We are now close to releasing IXP Manager v7, and it has become apparent that the single documentation site is suboptimal and confusing for people who have not upgraded but are reading about newer features. The best solution for this is to introduce major.minor versioning on the documentation site.
Material supports versioning via another tool called mike. For a new site, this is quite easy to set up and run, but we had to do the following for an existing site.
Quick side note: we are using a Python venv for mkdocs, mike, etc. and not installing system wide. One thing to watch out for is that mike calls mkdocs but this may not be in your path. This can be solved by updating the PATH environment variable or running mike as follows:
PATH=./venv/bin:$PATH mike deploy --push --update-aliases 7.0 dev
- Install mike per its and Material’s documentation.
- Delete the old documentation site:
mike delete --all - Deploy your current docs as the latest version:
mike deploy --push --update-aliases 6.4 latest - Deploy the docs you are working on for the upcoming version as the dev tag:
mike deploy --push --update-aliases 7.0 dev - Set the default docs:
mike set-default --push latest - We were using a custom CNAME for Github pages and a custom 404 page. These would have been removed with step (2) above but are both available in your documentation’s Githib repo under the gh-pages branch history. To restore these you need to place them back in the root folder of the gh-pages branch:
git checkout gh-pages
echo docs.ixpmanager.org >CNAME
wget https://raw.githubusercontent.com/$org/$repo/$hash/404.html
git add CNAME 404.html
git commit -am 'add back cname and 404'
git push