This is a simple example of how to use GitHub-Flavored Markdown with MkDocs Material (almost).

📚 Example document: https://kiyoon.kim/mkdocs-material-github-flavored-template

pip install -r requirements.txt

To preview the site,

mkdocs serve

• markdown-gfm-admonition simply replaces the github syntax to the pymarkdown admonitions syntax.
• docs/stylesheets/extra_admonitions.css defines additional admonitions (IMPORTANT, CAUTION).

See how it renders in the documentation!

> [!NOTE]
> This is a NOTE type alert.

> [!TIP]
> This is a TIP type alert.

> [!WARNING]
> This is a WARNING type alert.

> [!IMPORTANT]
> This is an IMPORTANT type alert.

> [!CAUTION]
> This is a CAUTION type alert.

Related configuration in mkdocs.yml:

markdown_extensions:
  - markdown_gfm_admonition

extra_css:
  - stylesheets/extra_admonitions.css

Using MathJax defined in docs/javascripts/mathjax.js.

$a^2 + b^2 = c^2$

$$
\begin{align*}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
\end{align*}
$$

$a^2 + b^2 = c^2$

$$ \begin{align*} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align*} $$

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Using gen-files and literate-nav. Basically scripts/gen_ref_nav.py will generate reference/SUMMARY.md file and then add to the navigation menu when you build it.

Relevant configuration in mkdocs.yml:

nav:
  # defer to gen-files + literate-nav
  - API reference:
      - mkdocstrings-python: reference/

plugins:
  - gen-files:
      scripts:
        - scripts/gen_ref_nav.py
  - literate-nav:
      nav_file: SUMMARY.md

Notice you can add modules to ignore in scripts/gen_ref_nav.py by adding to IGNORE_MODULES_* set.

IGNORE_MODULES_EXACT = {"my_project.my_module"}
IGNORE_MODULES_STARTSWITH = {"my_project.cli."}

When publishing a new version, the older versions will be archived with Mike.

The gh-pages branch will have the following structure:

📂 latest/
📂 v0.1.0/
📂 v0.1.1/
📂 v0.2.0/
...

• .github/workflows/check-docs.yml to check if the documentation builds successfully in PRs.
• .github/workflows/deploy-docs-on-latest.yml to deploy the documentation to GitHub Pages when you push to main/master branch.
• .github/workflows/deploy.yml to add a new tag, change docs/CHANGELOG.md based on conventional commits, deploy the documentation while keeping the previous versions, and create a GitHub release.