Deploying MkDocs to GitHub Pages with GitHub Actions

In this blog post, I will show how you can deploy your MkDocs to GitHub Pages with GitHub Actions.

Contents hide

1 What is MKDocs?

1.1 How to deploy a static site using MkDocs?

1.2 Setup GitHub repository and lets deploy a test static MkDocs site locally

2 Deploying MkDocs to GitHub Pages with GitHub Actions

2.1 Configure GitHub Pages to be source GitHub Actions

2.2 GitHub Actions workflow

2.2.1 build_mkdocs

2.2.2 deploy_mkdocs

3 Time to run in GitHub

What is MKDocs?

MKDocs is a great little tool for creating a static site, used commonly to store repository documentation, drawings, some examples etc!

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. Start by reading the introductory tutorial, then check the User Guide for more information.

https://www.mkdocs.org

How to deploy a static site using MkDocs?

Its very simple, installed using Python by:

pip install mkdocs

Setup GitHub repository and lets deploy a test static MkDocs site locally

I have now setup my GitHub repository, lets create an example MkDocs project

mkdocs new example-mkdocs

It has now created a folder with the basic structure of MKDocs:

MkDocs site can be ran locally using mkdocs serve :

mkdocs serve --config-file example-mkdocs/mkdocs.yml

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.08 seconds
INFO    -  [08:46:25] Watching paths for changes: 'example-mkdocs/docs', 'example-mkdocs/mkdocs.yml'
INFO    -  [08:46:25] Serving on http://127.0.0.1:8000/

I can successfully accessing when browsing to it locally

Deploying MkDocs to GitHub Pages with GitHub Actions

Awesome, now that we have an example MkDocs site, lets now deploy it to GitHub Pages!

Configure GitHub Pages to be source GitHub Actions

Pages source needs to be set to GitHub Actions, this is done via settings within your GitHub repository

GitHub Actions workflow

I will be using two jobs within my workflow:

build_mkdocs
deploy_mkdocs

build_mkdocs

  build_mkdocs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.9
      - run: pip install \
            mkdocs-material
      - run: mkdocs gh-deploy --config-file example-mkdocs/mkdocs.yml --force

This jobs steps:

Checkout the main branch
Setup Python

3. install mkdocs-material (using material as wanted to use a specific theme at the time)

4. running mkdocs gh-deploy – more on this command found in https://www.mkdocs.org/user-guide/deploying-your-docs/ (Running this, will deploy the site to a default branch of gh-pages within your repository)

deploy_mkdocs

Once the MkDocs documentation is built and deployed, the deploy_mkdocs job is triggered

  deploy_mkdocs:
    needs: build_mkdocs
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: gh-pages
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

This jobs steps:

Checks out the code from the gh-pages branch.
Configures GitHub Pages.
Uploads artifacts.
Deploys the uploaded artifacts to GitHub Pages using the “actions/deploy-pages” action.

Time to run in GitHub

The full workflow:

name: Build GitHub Pages
on:
  push:
    branches:
      - main
    paths:
      - 'example-mkdocs/**'
  workflow_dispatch:
permissions:
  contents: write
  pages: write
  id-token: write

jobs: 
  build_mkdocs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.9
      - run: pip install \
            mkdocs-material
      - run: mkdocs gh-deploy --config-file example-mkdocs/mkdocs.yml --force

  deploy_mkdocs:
    needs: build_mkdocs
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: gh-pages
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Success run, we can see both stages successful: