Document your project with MkDocs and GitHub Pages
Tags: github, documentation, mkdocs
Published: 2023-03-17 22:13:38

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](https://www.mkdocs.org). 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.
```zsh
pip install mkdocs python-markdown-math mkdocs-material
mkdocs new [dir-name]
```

This will create this default layout
```zsh
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/`:
```zsh
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.
```yaml
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.

{% details A few [extensions](https://python-markdown.github.io/extensions/) we added %} 

### [Admonition](https://python-markdown.github.io/extensions/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.
```

![Admonition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cteogs6ch3m6tkr8czd7.png)

### [Keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index)
```
++command+shift+n++
```

![Keys](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x67u1jbv5z96s0xabo6s.png)

### 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}$$
```

![Math](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lkymirvdd46zwr1vevud.png)
{% enddetails %}

<br>

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](https://docs.github.com/en/pages/quickstart) 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!