Recently I wanted to migrate the documentation of my C# WordPress library WordPressPCL from the GitHub wiki to something more flexible. With version 2 of the libaray coming soon the idea was to move all the docs into a static site hosted with GitHub Pages and managed in Markdown files. Luckily with mkdocs it’s pretty straight forward to get this up-and-running quickly.
Here’s what I wanted:
- Docs as markdown files in main repository with readthedocs theme
- Automatic build of the static website using GitHub Actions
- Deployment of static website to GitHub Pages
1. Docs as markdown files in main repository
mkdocs is a nice and easy way to create a static docs-style site from markdown – so exatly what I was looking for. It comes with a default theme but also the readthedocs style which I like.
On the main / master branch I created a docs folder and added an index.md file plus a few sub-pages inside folders matching my desired navigation hierarchy. This is just plain Markdown I copied from my GitHub Wiki, nothing special in regards to mkdocs.
To configure how the pages should be compiled I added a mkdocs.yml file into the root of the GitHub project where I configured the navigation & theme like this:
2. Automatic build of the static website using GitHub Actions
To automatically build the docs site using GitHub Actions I added this defintion file to my .github/workflows folder. This will also push the generated static files to the gh-pages branch of my repository using the mkdocs toolchain, where it can be picked up by GitHub.
3. Deployment of static website to GitHub Pages
Once step 2 was successful and the site was pushed to the gh-pages branch the only thing left to do is to enable GitHub Pages. This can be done from the settings page of the repository under Code and automation => Pages. Enabling this will automatically add another GitHub Action which will deploy the page whenever gh-pages is updated.
And here’s what the final result looks like for me: https://wp-net.github.io/WordPressPCL/