Documentation in GitHub Pages with mkdocs & readthedocs Theme

✍︎Photo by Gabriel Ghnassia on Unsplash

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:

1. Docs as markdown files in main repository with readthedocs theme
2. Automatic build of the static website using GitHub Actions
3. 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:

mkdocs.yml

site_name: WordPressPCL
site_url: https://wp-net.github.io/WordPressPCL/
nav:
    - Home: index.md
    - Version 2.x:
        - Getting Started: v2/getting-started.md
        - Types:
            - Comments: v2/types/comments.md
    - Version 1.x:
        - Types:
            - Comments: v1/types/comments.md
            - Posts: v1/types/posts.md


theme: readthedocs

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.

documentation.yml

# This is a basic workflow to help you get started with Actions

name: Docs

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the master branch
  push:
    branches: [ master ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v2
      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files
      - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
      - name: Publish docs
        run: mkdocs gh-deploy

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/

Originally published at https://medienstudio.net on March 27, 2022.