• 🛠️ MkDocs on macOS
• 📚 What is MkDocs?
  • ✅ Key Features
  • 📦 Is MkDocs open source?
  • 🔧 What can you build with MkDocs?
  • ✅ Requirements
  • 🔧 Step 1: Install MkDocs
    • (Optional) Add the Material theme:
  • 🧭 Step 2: Make the mkdocs command available
    • a) Check install location:
    • b) Add to PATH permanently (zsh):
  • 🚀 Step 3: Start a new MkDocs project
  • 🎨 Step 4: Enable the Material Theme
  • 🧩 Alternative: Run via Python module
• 📚 MkDocs Awesome Pages Plugin
  • ✅ Open Source
  • 🛠️ Installation
  • ⚙️ Configure mkdocs.yml
  • 📁 Folder structure & .pages files
    • Example structure:
  • 🔍 Example mkdocs.yml with plugin
  • 🔗 Further Resources

§🛠️ MkDocs on macOS

For my local documentation, I was looking for an open-source tool to create and manage my content. With MkDocs, I found a mature, widely used, and actively maintained solution.

I think this tool is worth writing an article about. I’m still new to it and don’t have much experience yet. What tools do you use to create your documentation locally?

§📚 What is MkDocs?

MkDocs is an open source tool for building static websites from Markdown files, designed specifically for technical documentation.

§✅ Key Features

§📦 Is MkDocs open source?

Yes. MkDocs is fully open source and licensed under the MIT License – free to use, modify, and redistribute.

• 🔗 GitHub: github.com/mkdocs/mkdocs
• 🔗 PyPI: pypi.org/project/mkdocs

§🔧 What can you build with MkDocs?

Examples include:

• Internal IT or team documentation
• Project or API documentation (e.g., GitHub projects)
• Manuals, Wikis, or checklists
• Offline technical knowledge bases

§✅ Requirements

• macOS (e.g., Ventura, Sonoma)
• Terminal basics
• Python installed

§🔧 Step 1: Install MkDocs

Install MkDocs locally for your user:

pip3 install --user mkdocs

§(Optional) Add the Material theme:

pip3 install --user mkdocs-material

This gives your documentation a modern, responsive design.

§🧭 Step 2: Make the mkdocs command available

By default, pip installs MkDocs in a directory not included in your PATH. To fix that:

§a) Check install location:

python3 -m site --user-base

Example output:

/Users/yourname/Library/Python/3.11

The relevant binary path is:

/Users/yourname/Library/Python/3.11/bin

§b) Add to PATH permanently (zsh):

echo 'export PATH=$PATH:/Users/yourname/Library/Python/3.11/bin' >> ~/.zshrc
source ~/.zshrc

Replace Python version if needed (3.11).

§🚀 Step 3: Start a new MkDocs project

mkdocs new my-docs
cd my-docs
mkdocs serve

Now open: http://127.0.0.1:8000

§🎨 Step 4: Enable the Material Theme

Edit mkdocs.yml:

theme:
  name: material

Then restart:

mkdocs serve

§🧩 Alternative: Run via Python module

If you see this error:

zsh: command not found: mkdocs

… you can always run MkDocs via:

python3 -m mkdocs serve

§📚 MkDocs Awesome Pages Plugin

The awesome-pages plugin for MkDocs automatically builds navigation from your folder structure – no need to manually define nav: in mkdocs.yml.

§✅ Open Source

• License: MIT
• Repo: github.com/lukasgeiter/mkdocs-awesome-pages-plugin

§🛠️ Installation

Install with pip:

pip3 install mkdocs-awesome-pages-plugin

§⚙️ Configure mkdocs.yml

Add the plugin:

plugins:
  - search
  - awesome-pages

⚠️ Remove the nav: section if you use this plugin – it will otherwise be ignored.

§📁 Folder structure & .pages files

Navigation is based on the folder structure under docs/.

§Example structure:

docs/
├── index.md
├── installation/
│   ├── prerequisites.md
│   └── setup.md
├── usage/
│   ├── start.md
│   └── features.md

→ The plugin auto-generates a menu from this.

§🔍 Example mkdocs.yml with plugin

site_name: My Tech Docs
theme:
  name: material

plugins:
  - search
  - awesome-pages

markdown_extensions:
  - admonition
  - toc:
      permalink: true

§🔗 Further Resources

• 📘 GitHub: mkdocs-awesome-pages-plugin
• 📘 PyPI: pypi.org/project/mkdocs-awesome-pages-plugin