Skip to content

Create a blog with MkDocs,mkdocs-material, mkdocs-rss-plugin and GitHub Pages

A few time ago I maintained a blog with Wordpress. I was happy with it, but I wanted to try something new.

I tried Jekyll but it didn't convince me, I discovered mkdocs so I decided to use MkDocs and mkdocs-material. I was happy with the result, so I decided to write this post to explain how to create a blog with MkDocs, mkdocs-material and some plugins.

These is the first post of a serie of posts to create a blog with MkDocs, mkdocs-material and GitHub Pages and some customization.

Some knowledge:

  • MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

  • Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. It is built using Google's Material Design guidelines. Material for MkDocs provides a polished and responsive experience out of the box, and it is as easy to use for the beginner as it is for the seasoned developer.

  • GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. You can see more information about GitHub Pages here.

  • This plugin generates an RSS feed for your MkDocs site. You can see more information about mkdocs-rss-plugin here.

Steps to deploy

Create a new repository

Create a new repository on GitHub named username.github.io, where username is your username (or organization name) on GitHub. If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right.

Enable GitHub Pages on your repository

Go into the repository settings and, if you are not using GitHub Pages already, enable GitHub Pages on the gh-pages branch.

Clone the repository

Go to the folder where you want to store your project, and clone the new repository:

git clone ssh://github.com/username/username.github.io
cd username.github.io

Create requirements.txt in root folder for mkdocs, mkdocs-material and plugins

mkdocs==1.5.3
mkdocs-material==9.4.6
mkdocs-rss-plugin==1.8.0

Create a Python Virtual Environment and install requirements.txt

In username.github.io$ path:

sudo apt update
sudo apt install libcairo2
sudo apt install python3.10-venv
python3 -m venv mysite
source mysite/bin/activate
pip install -r requirements.txt

Initialize your site

mkdocs new .

Add configuration to mkdocs.yml in root folder

For this post I am going to add the following configuration:

  • basic configuration
  • configuration for theme mkdocs-material
  • some native plugins of mkdocs-material and some ones that I like
site_name: My Site 
site_description: A blog about Azure, DevOps and other stuff
site_author: Rafael Fernández

theme: 
  name: material
  features:
    - navigation.tabs
    - navigation.expand
    - navigation.sections
    - toc.integrate
    - toc.nested
    - toc.smoothscroll
    - footer

plugins:
  - search  
  - blog
  - tags:
      tags_file: tags.md      

  - rss:
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

Add a new post

In blog/post folder create a new folder with the name of the post and create a new file with the name of the post and the extension .md. For example: welcome.md 

---
date: 2023-10-18
categories:
  - Hello
  - World
---

# "Hello world!!!" from mkdocs-material

...

Check your site

In username.github.io$ path:

mkdocs serve

You can check your site in http://127.0.0.1:8000/ and make live changes in your site and see the results in your browser.

Publish your site

In username.github.io$ path:

mkdocs gh-deploy

After a seconds, you can check your site in https://username.github.io/

Automate deploy with GitHub Actions

name: ci # (1)!
on:
  push:
    branches:      
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install -r requirements.txt # (4)!
      - run: mkdocs gh-deploy --force

  1. You can change the name to your liking.

  2. At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

  3. Store the cache_id environmental variable to access it later during cache key creation. The name is case-sensitive, so be sure to align it with ${{ env.cache_id }}.

    • The --utc option makes sure that each workflow runner uses the same time zone.
    • The %V format assures a cache update once a week.
    • You can change the format to %F to have daily cache updates.

    You can read the [manual page] to learn more about the formatting options of the date command.

  4. Add [MkDocs plugins] or Markdown extensions with pip to requirements.txt to be used during the build.

In the next post I will explain how to customize your site with mkdocs-material and some plugins writing mkdocs.yml.

That's it folks

urls for reference