This blog post contains the simplified steps, how to setup MkDocs for a GitHub project to use it with GitHub Pages. I won’t covering details about the background. The blog post is for me a little cheat sheet and maybe it is also useful for you. Steve Martinelli created an awesome blog post in that context called 5 Features I Like About Material for MkDoc.

Here an example GitHub project, which is based on the setup I documented in this blog post: https://thomassuedbroecker.github.io/How-to-install-MkDocs-on-Mac-and-setup-integration-with-GitHub/

The gif shows the example project documentation:

Local setup on Mac OS

• brew
• Python 3
• Pip
• MkDocs
• MkDocs Material Extensions

Configuration in the GitHub project

• GitHub CI
• GitHub Pages
• GitHub Branch

MkDocs installation on Mac

Step 1: Verify the brew installation

brew --version

Step 2: Change the folder permission to install python, if needed

sudo chown -R $(whoami) /usr/local/lib/pkgconfig
chmod u+w /usr/local/lib/pkgconfig

Step 3: Install python3

brew install python3

Step 4: Upgrade pip

pip3 install --upgrade pip

Step 5: Install mkdocs

pip3 install mkdocs

Step 6: Install mkdocs-material

pip3 install mkdocs-material

Step 7: Install mkdocs-material-extensions

pip3 install mkdocs-material-extensions

Verify and build your documentation

Step 1: Ensure you have the mkdocs.yml file in place

Here is an example configuration for the mkdocs.yml file and here you find an example project, which is based on that configuration.

# Project information
site_name: Your Project
site_url: https://[YOUR_GITHUB_ID].github.io/[your-repository-name]
site_author: Thomas Südbröcker

# Repository
repo_name: [YOUR-REPOSITORY-NAME]
repo_url: https://github.com/[YOUR_GITHUB_ID]/[YOUR-REPOSITORY-NAME]
edit_uri: edit/master/[YOU-DOCUMENTATION-FOLDER]
docs_dir: [YOU-DOCUMENTATION-FOLDER]

# Navigation
nav:
  - Welcome:
    - Overview: README.md   
  
## DO NOT CHANGE BELOW THIS LINE

# Copyright
# TBD

# Theme
theme:
  name: material
  font:
    text: IBM Plex Sans
    code: IBM Plex Mono
  icon:
    logo: material/library
  features:
    # - navigation.tabs
    - navigation.instant
    - navigation.expand
  palette:
    scheme: default
    primary: blue
    accent: blue

# Plugins
plugins:
  - search

# Customization
# TBD

# Extensions
markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

Step 1: Preview your documentation locally

python3 -m mkdocs serve  

• Example output:

INFO    -  Cleaning site directory 
INFO    -  Documentation built in 0.57 seconds 
[I 210125 09:15:48 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 210125 09:15:48 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 210125 09:15:48 handlers:64] Start detecting changes
INFO    -  Start detecting changes

Step 2: Build the pages in the folder “/site”, which will be added to your GitHub project

python3 -m mkdocs build

Integrate the documentation with GitHub CI

Step 1: Add folder to .gitignore

echo "site/" >> .gitignore

Step 2: Create two folders in your GitHub project folder

mkdir .github
cd .github
mkdir workflows

Step 3: Create a file called .github/workflows/ci.yml and insert the GitHub CI configuration which is listed here

name: ci
on:
  push:
    branches:
      - main
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Step 4: Create a new branch in your GitHub project called gh-pages

Note: That’s not necessary as the mkdocs gh-deploy command in the GitHub action will create the branch, if it’s not there. But I would say: “If you do it, your’e aware of it 😉 “

Step 5: Enable the GitHub pages on your project and select the branch gh-pages as source for your documentation

The gif below displays an update of the documentation, when you push changes to your GitHub project.

---

I hope this was useful for you and let’s see what’s next?

Greetings,

Thomas

#MkDocs, #brew, #python, #CI, #github, #githubpages