Skip to content

Instructions

This is the initial blank slate.

Steps so far

Basic install

Install mkdocs-material as a dev dependency.

1
pipenv install --dev mkdocs-material

Bootstrap the project with mkdocs new.

1
pipenv run mkdocs new .

Initial configuration is done in the mkdocs.yml file.

Add material theme

Enable the Material theme in the mkdocs.yml file.

1
2
theme:
  name: material

Add SuperFences

1
2
markdown_extensions:
  - pymdownx.superfences

Add git revision date

1
pipenv install --dev mkdocs-git-revision-date-plugin

1
2
plugins:
  - git-revision-date

Deploying github pages

Ensure github actions has read and write access to the repository.

Github actions permissions Github actions permissions

Add the following .github/workflows/pages.yml to the repository

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
name: ci 
on:
  push:
    branches:
      - main
    paths:
      - '.github/workflows/pages.yml'
      - 'docs/*'
      - 'mkdocs.yml'
      - 'Pipfile.lock'
      - 'Makefile'

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python 3.9
      uses: actions/setup-python@v3
      with:
        python-version: "3.9"

    - name: Install latest pipenv
      run: pip install -U pip pipenv

    - name: Install mkdocs dependencies
      run: make dev

    - name: Deploy to github pages
      run: make deploy

Once the workflow is deployed, update github pages to point to the new gh-pages branch

Github pages Github pages

Last update: 2022-05-10