Documentation Tool

MkDocs

Overview

MkDocs is a Python-based static site generator specifically designed for Markdown documentation. It focuses on building simple, clean documentation sites with rich theme and plugin ecosystems.

Details

MkDocs was developed by Tom Christie in 2014 and is widely adopted as a Markdown-based documentation creation tool. As part of the Python ecosystem, it can be easily installed via pip and configured intuitively through a configuration file (mkdocs.yml). Various themes, led by Material for MkDocs, enable building beautiful and functional documentation sites. The plugin system allows adding features like search functionality, internationalization, API documentation generation, and diagram creation. Live reload functionality enables real-time preview during development. Integration with GitHub and GitLab makes it easy to implement automatic deployment through CI/CD pipelines. Features like automatic navigation structure generation, cross-references, and table of contents generation support large-scale documentation projects. As of 2025, it is used as the standard documentation tool for many Python projects including Python, Django, and FastAPI, and is valued for its balance of simplicity and functionality. Custom theme development and plugin creation enable extensions tailored to specific needs.

Advantages and Disadvantages

Advantages

• Simple Configuration: Intuitive site structure through YAML configuration files
• Rich Themes: Numerous beautiful themes available including Material Design
• Plugin Ecosystem: Diverse functionality extensions for search, i18n, API documentation, etc.
• Python Ecosystem: Easy environment setup with pip install, strong Python compatibility
• Live Reload: Real-time preview and fast reflection during development
• Git Integration: Version control and collaboration through Markdown files
• Lightweight: Fast builds and minimal resource usage

Disadvantages

• Python Dependency: Python environment setup required
• Feature Limitations: Limited advanced interactive functionality
• Theme Learning: Understanding each theme's specifications required for customization
• Plugin Compatibility: Potential conflicts and compatibility issues between plugins
• Large Site Performance: Increased build times for very large sites
• Design Constraints: Limited frontend flexibility compared to React/Vue

Key Links

• MkDocs Official Site
• MkDocs Documentation
• GitHub Repository
• Material for MkDocs
• Plugin Catalog
• Theme Gallery

Usage Examples

Project Initialization

# Install MkDocs
pip install mkdocs

# Create project
mkdocs new my-project
cd my-project

# Project structure
my-project/
    mkdocs.yml    # Configuration file
    docs/
        index.md  # Homepage

Basic mkdocs.yml Configuration

site_name: Project Documentation
site_url: https://example.com/docs
repo_url: https://github.com/username/project
repo_name: username/project
edit_uri: blob/main/docs/

# Navigation structure
nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quickstart.md
  - User Guide:
    - Basics: user-guide/basics.md
    - Advanced Features: user-guide/advanced.md
  - API Reference:
    - Classes: api/classes.md
    - Functions: api/functions.md
  - Developer Guide:
    - Contributing: developers/contributing.md
    - Testing: developers/testing.md

# Theme configuration
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.highlight
    - search.suggest
    - content.tabs.link
    - content.code.annotation
    - content.code.copy
  language: en

# Markdown extensions
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - toc:
      permalink: true
  - meta
  - def_list
  - attr_list
  - md_in_html

# Plugins
plugins:
  - search:
      lang: en
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: sphinx
  - git-revision-date-localized:
      type: date
      locale: en

# Additional CSS and JavaScript
extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

# Extra variables
extra:
  version: 1.0.0
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username/project
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username

Writing Markdown Documentation

---
title: API Reference
description: Project API specification
---

# API Reference

This page provides detailed information about the project's API.

## Classes

### UserManager

The `UserManager` class is the core class for user management.

```python
class UserManager:
    """Class for managing users
    
    Attributes:
        users (list): List of users
        active_count (int): Number of active users
    """
    
    def __init__(self):
        self.users = []
        self.active_count = 0
    
    def add_user(self, user):
        """Add a new user
        
        Args:
            user (User): User to add
            
        Returns:
            bool: True if addition was successful
        """
        if self.validate_user(user):
            self.users.append(user)
            return True
        return False

!!! note "Usage Notes" Always validate users with the validate_user() method before adding them.

!!! warning "Important" This API is experimental and may change in future versions.

Configuration Examples

=== "Python" ```python from user_manager import UserManager

# Create instance
manager = UserManager()

# Add user
user = User(name="John Doe", email="[email protected]")
manager.add_user(user)
```

=== "YAML" yaml user_manager: max_users: 1000 validation: email_required: true name_min_length: 2

=== "JSON" json { "user_manager": { "max_users": 1000, "validation": { "email_required": true, "name_min_length": 2 } } }

Flowchart

graph TD
    A[User Registration Start] --> B{Input Validation}
    B -->|Success| C[Create User]
    B -->|Failure| D[Display Error Message]
    C --> E[Save to Database]
    E --> F[Send Registration Email]
    F --> G[Registration Complete]
    D --> H[Request Re-entry]
    H --> A

Related Pages

• Installation Guide
• Configuration Reference
• Troubleshooting

### Plugin Configuration Examples
```yaml
# Detailed plugin configuration in mkdocs.yml

plugins:
  # Search plugin
  - search:
      lang: ['en', 'ja']
      separator: '[\s\-\.]+'
      prebuild_index: true

  # API documentation auto-generation
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: sphinx
            show_root_heading: true
            show_source: true
            show_bases: true
            show_submodules: true

  # Git information display
  - git-revision-date-localized:
      type: timeago
      locale: en
      fallback_to_build_date: true

  # Sitemap generation
  - sitemap:
      pretty: true
      format: xml

  # Multilingual support
  - i18n:
      default_language: en
      languages:
        en: English
        ja: Japanese
      nav_translations:
        en:
          Home: Home
          About: About

  # PDF output
  - with-pdf:
      cover_title: Project Documentation
      cover_subtitle: Version 1.0
      output_path: pdf/document.pdf

  # Macro functionality
  - macros:
      include_dir: includes
      variables:
        project_version: 1.0.0
        api_base_url: https://api.example.com

Custom Theme Creation

# setup.py - Custom theme package
from setuptools import setup, find_packages

setup(
    name="mkdocs-custom-theme",
    version="1.0.0",
    description="Custom MkDocs theme",
    packages=find_packages(),
    include_package_data=True,
    entry_points={
        'mkdocs.themes': [
            'custom = custom_theme',
        ]
    },
    install_requires=[
        'mkdocs>=1.0'
    ],
    zip_safe=False
)

# custom_theme/mkdocs_theme.yml - Theme configuration
extends: material
vars:
  primary_color: '#2196F3'
  accent_color: '#FF9800'
  font_family: '"Roboto", sans-serif'
  show_sidebar: true
  enable_search: true

<!-- custom_theme/main.html - Main template -->
{%- extends "base.html" %}

{% block site_meta %}
  {{ super() }}
  <meta name="author" content="{{ config.site_author }}">
  <meta property="og:image" content="{{ config.site_url }}{{ config.theme.logo }}">
{% endblock %}

{% block content %}
  {{ super() }}
  
  {% if page.meta.api %}
    <div class="api-badge">
      <span>API Documentation</span>
    </div>
  {% endif %}
{% endblock %}

{% block footer %}
  <footer class="md-footer">
    <div class="md-footer-meta md-typeset">
      <div class="md-footer-meta__inner md-grid">
        <div class="md-footer-copyright">
          <div class="md-footer-copyright__highlight">
            © {{ config.copyright }}
          </div>
          Last updated: {% if page.meta.git_revision_date_localized %}
            {{ page.meta.git_revision_date_localized }}
          {% endif %}
        </div>
      </div>
    </div>
  </footer>
{% endblock %}

Automated Deployment Configuration

# .github/workflows/docs.yml - GitHub Actions
name: Build and Deploy Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          key: ${{ github.ref }}
          path: .cache

      - name: Install dependencies
        run: |
          pip install -r requirements.txt

      - name: Build documentation
        run: |
          mkdocs build --strict

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

Development Workflow

# Start development server
mkdocs serve

# Start on specific port
mkdocs serve --dev-addr localhost:8080

# Production build
mkdocs build

# Validate site
mkdocs build --strict

# Clean build
mkdocs build --clean

# Debug plugins
mkdocs serve --verbose

# Validate configuration file
python -m mkdocs config

Plugin Development Example

# mkdocs_plugin_example.py
from mkdocs.plugins import BasePlugin
from mkdocs.config import config_options

class ExamplePlugin(BasePlugin):
    config_scheme = (
        ('enabled', config_options.Type(bool, default=True)),
        ('prefix', config_options.Type(str, default='Example:')),
    )
    
    def on_page_markdown(self, markdown, page, config, files):
        if not self.config['enabled']:
            return markdown
            
        # Markdown transformation process
        if page.title:
            prefix = self.config['prefix']
            markdown = f"{prefix} {markdown}"
            
        return markdown
        
    def on_page_content(self, html, page, config, files):
        # HTML post-processing
        if 'api' in page.meta:
            html = f'<div class="api-content">{html}</div>'
        return html