I’ve been using Hugo for a while and it also powers this blog. However, for my tiny Yzl project I wanted GitHub Pages docs that look like this. I’ve seen it in numerous open-source projects and I liked the material design look. If you like it too, please keep reading.

What is it? ¶

After a quick research I have found out that the tool is mkdocs and the theme I want is squidfunk/mkdocs-material. 2 minutes later I started playing with mkdocs. In the root of my repo I created docs folder with a placeholder index.md and ran:

docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs \
  squidfunk/mkdocs-material new .

It created mkdocs.yml file which holds all the configuration for the docs. I edited it to look like:

site_name: Yzl
nav:
- Home: index.md
theme: 
  name: material
  palette:
    primary: teal

Then I ran the following and got a preview:

docker run -p 8089:8089 --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs \
  squidfunk/mkdocs-material serve -a 0.0.0.0:8089

I was happy with my version 1 and published it with:

docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs \
  squidfunk/mkdocs-material gh-deploy 

The command has created gh-pages branch and committed and pushed the newly generated content.

The last step was to set up GitHub Pages to point to gh-pages branch in my repo settings in GitHub. Shortly after my docs were published.

So that was the easy part. Now I need to write the docs.