Material for MkDocs¶

This website was created using Material for MkDocs, a simple yet powerful framework for creating documentation. All it requires is a Markdown file for every page, and a configuration file that connects everything together. With Material for MkDocs providing [somewhat] customizable features, frontend, and deployment methods, I can focus my time on the content of the site.

Useful Documentation Pages¶

Setup¶

Page Tree Example¶

Based on this site. Paths in the page tree are relative to docs/.

nav:
  - Home: index.md                      # Homepage, first tab
  - Setup:                              # Second tab
    - setup/index.md                    # Second tab homepage
    - Settings: setup/settings.md       # Second tab first page
  - Reference:                          # Third tab
    - Mkdocs: reference/docker.md.md    # Third tab first page (no third tab homepage)

Plugins¶

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

Automatic documentation generation using mkdocstrings
Page revision time using mkdocs-git-revision-date-localized-plugin
- Note: times are in UTC

Reference¶

Demonstrations of the features I use. View this page raw for the Markdown syntax used. View the documentation reference for what be in the configuration file to enable a feature.

Collapsible blocks, code block formatting, embedding external files¶

Click to toggle open/close

Syntax highlighting for inline code: Python's range() function...

Embed of docs/reference/mkdocs.md
mkdocs-git-revision-date-localized-plugin==1.*
mkdocs-material==9.*

# social plugin dependencies

cairosvg
pillow

Content tabs, icons, glossary¶

Markdown:

docs/example.md includes/abbreviations.md

1. Use the term (i.e. "WSL")
2. Import glossary by adding to end of the file: --8<-- "includes/abbreviations.md"

Define the term
```
*[WSL]: Windows Subsystem for Linux
```

Result:

WSL is a term in the glossary.

Table, keyboard keys¶

Shortcut	Description
`Alt` + (`Shift`) + `Tab`	Navigate between windows
`Win`+`Ctrl` + `Left`/`Right`	Navigate between virtual desktops
`F11`	Fullscreen

Task list, inline math equations¶

Result of task list
Prove \(e=mc^2\)

Bug: Line break workaround in math equations

CI / CD Using GitHub Actions¶

Deploy¶

The Materials for MkDocs documentation gives an example deploy workflow. I modified it slightly to properly support page revision times using mkdocs-git-revision-date-localized-plugin. I also used encrypted secrets to use Google Analytics without exposing the key. This workflow is run on every push to the main branch

Deploy workflow¶

Deploy workflow for this project

.github/workflows/deploy.yml
1

Lint¶

Markdown linter¶

I use markdownlint to check for programmatic and stylistic errors in the application's Markdown files.

I configured the errors using a .markdownlint.json file in the project's root directory to support the syntax of Material for MkDocs features. This workflow is run on every push and pull request to the main branch.

markdownlint configuration for this project

.markdownlint.json
{
  "default": true,
  "MD013": {
    "line_length": 180,
    "tables": false
  },
  "MD004": {
    "style": "dash"
  },
  "MD007": {
    "indent": 4
  },
  "MD033": {
    "allowed_elements": ["figure", "figcaption"]
  },
  "MD035": {
    "style": "---"
  },
  "MD040": false,
  "MD041": false,
  "MD046": false
}

markdownlint resources:

Check Markdown links¶

I check for broken links using markdown-link-check. This action checks links to pages on the internet (https://www.google.com) and files in the repository (./index.md). However, it does not check whether a section exists in the file (./index.md#overview). This workflow is run on every push and pull request to the main branch, as well as on a schedule.

Lint workflows¶

Lint workflow for this project

.github/workflows/lint.yml
1

Scheduled Tasks workflow for this project

.github/workflows/scheduled_tasks.yml
name: Scheduled Tasks

on:
  schedule:
    # Every Saturday at 11:00am UTC
    - cron: '0 11 * * 6'

jobs:
  # https://github.com/gaurav-nelson/github-action-markdown-link-check
  markdown-link-check:
    runs-on: ubuntu-latest
    steps:
    - name: Check out code
      uses: actions/checkout@v2

    - name: Check markdown pages for broken links
      uses: gaurav-nelson/github-action-markdown-link-check@v1
      with:
        config-file: '.mlc_config.json'
        folder-path: 'docs, includes'

Resources¶

Schedule workflow runs

Example Sites¶

Material for MkDocs and Pymdown Extensions documentation
up42
- Uses the mkdocstrings plugin for the Code Reference
This site!

Last update: July 16, 2022