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¶

mkdocs new [dir-name] - Create a new project.
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs help - Print this help message.

Install and documentation generation¶

mkdocs.org.

To install MkDocs / create a new documentation site:

uv tool install mkdocs --with mkdocs-material --with mkdocs-minify-plugin --with mkdocs-redirects
mkdocs new documentation

To build the documentation site:

cd documentation
mkdocs build

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

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:

mkdocs gh-deploy

MkDocs project layout¶

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