NostrHTTP - <h1>🛠️ MkDocs on mac

导航栏

Home

@ avren
2025-05-07 07:16:54
🛠️ 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:

bash pip3 install --user mkdocs

(Optional) Add the Material theme:

bash 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:

bash 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):

bash 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

bash 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:

yaml theme: name: material

Then restart:

bash mkdocs serve

🧩 Alternative: Run via Python module

If you see this error:

zsh: command not found: mkdocs

… you can always run MkDocs via:

bash 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:

bash pip3 install mkdocs-awesome-pages-plugin

⚙️ Configure mkdocs.yml

Add the plugin:

yaml 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

```yaml 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
yakihonne.com iris.to jumble.social