Skip to content

MkDocs and GitHub Pages

This website was created using MkDocs, surrounding python packages like mkdocs-material, and is served with GitHub pages.

About MkDocs and its plugins

The MkDocs library makes it easy to create documentation from just markdown and YAML files.

With just a few commands, you can quickly iterate with your content and make some great looking webpages.

There is also a handful plugin libraries for MkDocs that allow for additional customization. For instance, the theme used here is from the mkdocs-material package. Makes it so easy to have a good looking site on all platforms (especially for people like me who don't make user interfaces often 😄).

Creating the Content and Theme

MkDocs really makes it so easy to set up a page. The Getting Started Section allows you to get started.

The simpliest project setup will just be two files:

The themes and capabilities were inspired from the mkdocs-material site and exploring its mkdocs.yml helped implement mine.

Serving with GitHub Pages

GitHub allows you to set up a site for free. If the repo is named <username>.github.io, then it will be hosted at https://<username>.github.io.

Tip

If you deploy with GitHub pages in any other repo, the docs with be hosted at https://<username>.github.io/<repo-name>. Super cool and would like to use in the future to make quick project documentation!

All the code to create this site is on my GitHub here.

GitHub Action

The mkdocs-material documentation has the steps in order to set up your GitHub Action for deploy. Those steps are found here.

GitHub Page Settings

I had some hiccups while setting up the site. Initially, only my README was being served at https://wd60622.github.io. However, the default "Deploy from a branch" setting in the GitHub Pages section was on the main branch which only had the README.

Note

Running mkdocs gh-deploy pushes all the html files to gh-pages branch in my repo so that branch needed to be selected in the Settings.

Below are Settings section that worked for my deployment.

GitHub Page Setting

I found these links helpful while setting up this site and writing this post.

Comments