Using mkdocs with GitHub pages (pitfalls)

Using mkdocs with GitHub pages (pitfalls)

All of you using GitHub already probably heard about their new feature to publish your own static website of the project via GitHub Pages. The default static pages generator for GitHub-pages is Jekyll, but we prefered to use MkDocs for generating our user guide with the style close to Read the Docs.

However, when you start reading the help pages on how to start with GitHub-pages (or gh-pages) then you active gh-pages via the ‘Setting’ of your project. That is fine if you stick to Jekyll and the themes gh-pages has available to you, but if you want to use mkdocs (or something else) do not active the gp-pages. Of course, I was using mkdocs and had to learn the heard way and actived gh-pages as follow:

Followed by a mkdocs gh-deploy (which succeeded).

However, then you will get a page 404 (File not found) to see when you click on the URL shown above. The reason is that gp-pages (once actived via the Settings) only works fine when you use Jekyll as web page generator. I spent several hours to figure out how to fix this and tried several settings, but nothing worked. Until I stumbled over “The Perfect Documentation Storm” page which made my euro-cent drop and realized that gp-pages may not be activated via settings (of the project page) to work with non-Jekyll static web page generators. Therefore, first delete the branch ‘gh-pages’ (via “code” -> “branches” -> “Delete the branch gh-pages”). Afterwards, go back to the “Settings” of your project and set the Source to “None” as show below:

However, gh-pages requires the branch “gh-pages” to publish something on the web, therefore, do the following:

gdha@velo:~/web$ mkdocs gh-deploy
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/gdha/web/site 
INFO    -  Documentation built in 0.08 seconds 
INFO    -  Copying '/home/gdha/web/site' to 'gh-pages' branch and pushing to GitHub. 
INFO    -  Your documentation should shortly be available at: https://gdha.github.io/pi-stories/ 

And, finally, check the URL and you see the result on the Internet. This made my day and to avoid others to fall into the same pitfall I thought to share it with you all.

References:

[1] mkdocs

[2] GitHub Pages

[3] The Perfect Documentation Storm

Edit history

• Initial post on 14 August 2020