MkDocs — Everything You Need, Nothing You Don't

Published: February 24, 2026 · Last edited: February 24, 2026

TL;DR — MkDocs turns Markdown files into a static documentation site. Configure with one YAML file, serve locally, deploy anywhere.

---

⚡ Quickstart (copy-paste and go)

pip install mkdocs mkdocs-material   # install
mkdocs new my-docs && cd my-docs     # scaffold project
mkdocs serve                         # live-reload dev server → http://127.0.0.1:8000
mkdocs build                         # output static site to ./site/

---

📁 Project Structure

my-docs/
├── mkdocs.yml        ← THE config file (everything lives here)
└── docs/
    ├── index.md      ← homepage
    ├── guide/
    │   └── setup.md
    └── api/
        └── reference.md

Rule: file path in docs/ = URL path on your site. docs/api/reference.md → /api/reference/

---

🔧 mkdocs.yml — The Only Config File You Need

site_name: My Docs
site_url: https://yourname.github.io/my-docs/
repo_url: https://github.com/yourname/my-docs   # adds GitHub link in header

theme:
  name: material   # best theme, use it

# Explicit nav (optional — MkDocs auto-generates if omitted)
nav:
  - Home: index.md
  - Setup Guide: guide/setup.md
  - API Reference: api/reference.md

# Useful plugins
plugins:
  - search                  # built-in search
  - awesome-pages           # auto-nav from folder structure

# Markdown extensions (highly recommended)
markdown_extensions:
  - admonition              # note/warning/tip callout boxes
  - pymdownx.superfences    # code blocks with syntax highlighting
  - pymdownx.tabbed:        # tabbed content
      alternate_style: true
  - pymdownx.highlight:     # syntax highlighting
      anchor_linenums: true
  - toc:                    # table of contents
      permalink: true
  - attr_list               # add HTML attributes to elements
  - md_in_html              # markdown inside HTML blocks

---

🎨 Material Theme (Just Use It)

pip install mkdocs-material

theme:
  name: material
  palette:
    scheme: slate          # dark mode
    primary: indigo
    accent: cyan
  features:
    - navigation.tabs        # top-level sections as tabs
    - navigation.sections    # expand sections in sidebar
    - navigation.top         # "back to top" button
    - content.code.copy      # copy button on code blocks
    - search.highlight
    - search.suggest

---

📝 Markdown Features Worth Knowing

Callout Boxes (admonition)

!!! note "Optional Title"
    This is a note. Other types: `warning`, `tip`, `danger`, `info`, `success`

??? tip "Collapsible"
    Click the arrow to expand.

Code Blocks

```python title="example.py" linenums="1" hl_lines="2 3"
def hello():
    print("highlighted")   # line 2
    return True            # line 3
```

Tabs

=== "Python"
    ```python
    print("hello")
    ```

=== "JavaScript"
    ```js
    console.log("hello")
    ```

Content Grids (Material)

<div class="grid cards" markdown>
- :fontawesome-brands-python: **Python SDK** — Install with `pip`
- :material-api: **REST API** — Full OpenAPI spec
</div>

---

🔌 Plugins Worth Installing

Plugin	Install	What it does
mkdocs-material	pip install mkdocs-material	Best theme, tons of features
mkdocs-awesome-pages-plugin	pip install mkdocs-awesome-pages-plugin	Auto-nav from folder structure + ordering via .pages files
mkdocs-git-revision-date-localized-plugin	pip install ...	Shows last git commit date on pages
mkdocs-minify-plugin	pip install mkdocs-minify-plugin	Minifies HTML/JS/CSS output
mkdocstrings	pip install mkdocstrings[python]	Auto-generate API docs from docstrings

mkdocstrings (API docs from code)

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true

Then in any .md file:

::: mymodule.MyClass

---

🚀 Deployment

GitHub Pages (easiest)

mkdocs gh-deploy   # builds + pushes to gh-pages branch automatically

GitHub Actions (automated on push)

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # needed for git-revision-date plugin
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Other Targets

• Netlify/Vercel — build command: mkdocs build, publish dir: site
• S3/GCS — sync the site/ folder
• Self-hosted — serve site/ with nginx/caddy (it's just static files)

---

🗂️ Nav Control Without Writing It All By Hand

Install mkdocs-awesome-pages-plugin, then use .pages files in each folder:

# docs/guide/.pages
nav:
  - Overview: overview.md
  - ...          # auto-include rest alphabetically

Or just omit nav from mkdocs.yml entirely and let MkDocs auto-build it from your folder structure.

---

🐛 Common Gotchas

Problem	Fix
Page not showing in nav	Add it to nav: in mkdocs.yml or remove nav: entirely to auto-generate
Broken links in build	Use relative paths (../other-page.md) not absolute URLs
site/ committed to git	Add site/ to .gitignore
Admonitions not rendering	Add admonition to markdown_extensions:
Code copy button missing	Add content.code.copy to theme.features:
Slow builds	Use mkdocs serve --dirty (only rebuilds changed pages)

---

🔑 CLI Reference

mkdocs new [dir]          # scaffold new project
mkdocs serve              # dev server with live reload
mkdocs serve --dirty      # faster: only rebuild changed files
mkdocs build              # generate static site → ./site/
mkdocs build --clean      # wipe site/ first, then build
mkdocs gh-deploy          # build + deploy to GitHub Pages
mkdocs gh-deploy --force  # force push (good for CI)
mkdocs --help             # you know what this does

---

📦 Minimal requirements.txt for Docs

mkdocs>=1.5
mkdocs-material>=9.0
mkdocs-awesome-pages-plugin
mkdocstrings[python]

---

That's it. For edge cases: mkdocs.org and squidfunk.github.io/mkdocs-material