Documentation is one of the most important pieces in any software project. Without documentation, it becomes harder to onboard new developers or gather community feedback, since there is no clear understanding of what the project is about or how to use it. On the other hand, documentation might exist, but it can sometimes be a nightmare to find the actual information due to a lack of search functionality, and aesthetically, it might just not be pleasing to look at.

Recently I was looking into creating a command-line interface in Python. In the past I’ve used Go’s Cobra for developing CLIs, but for this project, most of the service code was in Python. Naturally, we wanted to keep the codebase tight, with no language fragmentation. I stumbled upon Typer with a solid ecosystem over 18.000+ stars and active contributors so it seemed like the natural choice.

However, as I was learning more about Typer, something caught my eye: its beautiful and extensive documentation. It made getting started a breeze, and it turns out it was built with Mkdocs Material .

I actually had a need to create a few documentation sites for different scientific projects at work. These projects already had software but were missing documentation.

Let’s walk through how to set up MkDocs Material and get a documentation site up and running.

Mkdocs Material Installation

For this I will be using uv as the package manager, but feel free to follow along with the default venv, conda, or anything else you like. Installing mkdocs is simple, we just run the following commands:

# create a virtual environment
uv venv --python=3.10
source .venv/bin/activate

uv pip install mkdocs-material

Great, now we are ready to use it to create our documentation. We will want to achieve the following in order to get a simple docs site up and running:

1. Documentation structure
2. Configuring site via mkdocs.yaml
3. Adding content
4. Deploy on github pages

Setting Mkdocs Material Structure

The only two requirements we need to setup a valid Mkdocs material are:

• A mkdocs.yaml at the root of the project, which will configure our website
• A docs/ folder, where our content files will go

Let’s run the following commands to get our project started:

mkdir my_doc_site
cd my_doc_site

# create the mkdocs structure
mkdocs new .

Awesome! we should now have the following structure:

my_doc_site/
|
|---docs/
|   |
|   ---index.md
|---mkdocs.yaml

1. Documentation structure
2. Configuring site via mkdocs.yaml
3. Adding content
4. Deploy on github pages

Configuring Our Site

The file mkdocs.yaml will serve as the configuration file for our site. There is an extensive list of fields you can set, but for now, we can go with the minimal setup and enable material as the theme.

site_name: My Documentation Site
site_url: https://mydomain.org/mysite
theme:
  name: material

1. Documentation structure
2. Configuring site via mkdocs.yaml
3. Adding content
4. Deploy on github pages

Adding content

Earlier we mentioned that we use the docs/ directory to place our content, so let’s do that. Let’s add an extra about page with the following command:

touch docs/about.md

echo 'This is my about page!' >> docs/about.md

Fantastic, we can now look at what we have by running:

mkdocs serve

If we check localhost:8000 , we should now see our site with already a lot of structure baked in such as a navbar, search bar, navigation links, and a table of contents for the current page.

Let us visit the about page. We can then see the content that we have put in before.

1. Documentation structure
2. Configuring site via mkdocs.yaml
3. Adding content
4. Deploy on github pages

Deploy on Github Pages

Lastly, we want to make our documentation site accessible, so we can distribute and reference it in the future. Let us setup a github action that will automate the process for us whenever we modify our documentation and push to our main branch.

 1name: Deploy documentation page
 2
 3on:
 4  push:
 5    paths:
 6      - "docs/**"
 7      - "mkdocs.yml"
 8    branches:
 9      - main
10
11jobs:
12  deploy:
13    runs-on: ubuntu-latest
14
15    steps:
16      - name: Checkout repo
17        uses: actions/checkout@v5
18
19      - name: Set up Python
20        uses: actions/setup-python@v5
21        with:
22          python-version: "3.10"
23
24      - name: Install mkdocs
25        run: |
26          pip install mkdocs-material
27
28      - name: Deploy to GitHub Pages
29        run: |
30          mkdocs gh-deploy --force # easy command to deploy into github_pages branch
31        env:
32          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Important

Setup the deployment under Settings > Pages to be done from gh-pages branch then click Save.

1. Documentation structure
2. Configuring site via mkdocs.yaml
3. Adding content
4. Deploy on github pages

That it is! We have deployed our documentation using GitHub Pages and can now distribute it as needed. As an exercise you can check out the Mkdocs Material Reference to add things like admonitions, tables, and more. Also, you can explore how to add custom routing or themes with palette support for light/dark modes.

Resources:

• Mkdocs Material
• Mkdocs Material Reference
• Mkdocs Material Advanced Configurations
• Some inspiration sites Typer , NSDF Dark Matter , The SOMOSPIE project , The GEOtiled project