About Material for MkDocs¶

Material for MkDocs is a documentation framework based on MkDocs.

It has a better looking interface than plain MkDocs and offers various features to help organize your documentation with Markdown.

How and why do we use Material for MkDocs¶

We use Material for MkDocs to generate the documentation website.

Install Material for MkDocs¶

Install Material for MkDocs with the following commands.

1
2
3
4
5
6
7

# Install Material for MkDocs and all its extensions
pip install --user \
    cairosvg \
    mkdocs-git-revision-date-localized-plugin \
    mkdocs-glightbox \
    mkdocs-material \
    mkdocs-minify-plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Install Material for MkDocs and all its extensions
pip3 install \
    cairosvg \
    mkdocs-git-revision-date-localized-plugin \
    mkdocs-glightbox \
    mkdocs-material \
    mkdocs-minify-plugin \
    pillow

# Install Material for MkDocs dependencies
brew install \
    cairo \
    freetype \
    libffi \
    libjpeg \
    libpng \
    zlib

1

TODO

You can use the dev container to develop within. You can read more here.

Once in the dev container you can run the following commands:

1
2
3
4

# Activate the virtual environment
poetry shell
# Install the dependencies
poetry install

Configuration¶

The configuration for Material for MkDocs is located in the mkdocs.yml configuration file.

Common tasks¶

Start the website for development¶

1

mkdocs serve --dev-addr 0.0.0.0:8000

Build the website for production¶

1

mkdocs build --strict --site-dir public

Add a new page¶

Add a new page by creating a new file/directory in the docs directory. All pages must have a .md file extension.

Add a new navigation entry¶

Add a new entry to the navigation in the mkdocs.yml file under the nav property.

Add a new glossary entry¶

Add a new entry to the glossary in the docs/glossary.md file.

The format must be as follow.

1

*[Abbr]: The full definition of the abbreviation

Each word that Material for MkDocs will find in the documentation will have a tooltip with the definition for the word.

Resources and alternatives¶

These resources and alternatives are related to the current item (in alphabetical order).

• Docsify
• Docusaurus
• GitBook
• Hugo
• Material for MkDocs - Icons, Emojis
• PyMdown Extensions Documentation - Keys
• VuePress