MkDocs Basics¶

MkDocs is a fast, simple, and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

This website is generated by mkdocs.org and the Material Theme.

Basic MkDocs Commands¶

just uv run mkdocs serve starts the live-reloading docs server.
just uv run mkdocs build builds this documentation site.
just uv run mkdocs --help prints the help message.

Install and documentation generation¶

mkdocs.org.

In this repository, sync the locked MkDocs tools before creating or serving the site:

just sync
just uv run mkdocs new documentation

To build the documentation site:

just uv run mkdocs build

To start the live-reloading docs server - https://localhost:8000/

just uv run mkdocs serve

MkDocs can use the ghp-import tool to commit to the gh-pages branch and push the gh-pages branch to GitHub Pages:

just uv run mkdocs gh-deploy

MkDocs project layout¶

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

Material for MkDocs Best Practices¶

Use the mkdocs.yml to leverage the Material theme extensively:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode