🛠️ 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#

Feature	Description
📄 Markdown-based	Write content in .md files (e.g., with Zettlr, VS Code, Obsidian)
🌐 Static site output	MkDocs renders a full HTML site with navigation, search, and styling
🎨 Themes available	Most popular: Material for MkDocs
🔄 Live preview	Use mkdocs serve to view the docs locally in your browser
🔧 Simple configuration	Controlled via a single mkdocs.yml file
🔐 No cloud required	Fully local, ideal for privacy and offline work

---

📦 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