Document your project with MkDocs and GitHub Pages

Most project documentation starts with a single README.md file. But for medium and large projects this quickly becomes a really long and hard to manage file. Searching for the content you want, navigation, and styling become a mess.

Enter MkDocs. It can generate a static site that can be hosted on any web server. We'll set it up on GitHub Pages with a configuration that not only makes it look great but allows rich content like math expressions and simplifies deployment.

First install the needed software and create the file structure we'll use.

pip install mkdocs python-markdown-math mkdocs-material
mkdocs new [dir-name]

This will create this default layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

GitHub Pages gives you the option to host your static site on any branch in either the root of your project or in a /docs folder so we'll modify the default layout to make our lives easier. Rename /docs to /src/:

mv ./docs/ ./src/

and move the whole dir with mkdocs.yaml and /src/ to your project's directory.

Now edit your mkdocs.yml file to look like this. Replace the placeholders with your GitHub username and repo.

site_name: My Site
site_url: https://<user>.github.io/<repo>/
repo_url: https://github.com/<user>/<repo>
nav:
  - Home: 'index.md'
markdown_extensions:
  - toc:
    permalink: "#"
theme:
  name: material
  features:
    - navigation.expand
    - navigation.top
    - content.code.copy
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-5
        name: Switch to dark mode
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-3
        name: Switch to light mode
extra_javascript: 
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML
markdown_extensions:
  - mdx_math
  - admonition
  - sane_lists
  - pymdownx.highlight:
      auto_title: false
  - pymdownx.superfences
  - pymdownx.keys
docs_dir: src
edit_uri: edit/main/src/
site_dir: docs

Notice we set docs_dir: src to hold our .md files and site_dir: docs to automatically place the generated site in the folder that GitHub uses to serve our GitHub Pages site.

We're also using the Material theme which is clean, elegant, and has great customization options.

A few extensions we added

Admonition

• Pencil: attention, caution, error, hint, important,note.
• Fire: tip.
• Exclamation mark: warning.
• Lightning bolt: danger.

The text must be indented.

!!! attention
    Text goes here.

Keys

++command+shift+n++

MathJax

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

Now generate the site. You can use the live-reloading site during development and when you're ready to deploy, build the production site.

• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.

Almost ready!

• Enable GitHub Pages for your project. Make sure you set it to use the main branch and the /docs folder.
• Commit your changes and push them to GitHub.

This will kick off a GitHub Action to serve your site. After about a minute it will be available at username.github.io/repo.

Go ahead and create stunning technical documentation for your project!