mkdocs-django

A reusable Django application that integrates MkDocs documentation with Django's staticfiles framework, allowing you to serve your documentation as part of your Django project.

Features

• Django Integration: Seamlessly integrates with Django's staticfiles framework
• MkDocs Python API: Uses MkDocs' internal Python API for building documentation
• Custom Staticfiles Finder: Integrates with collectstatic for deployment
• Flexible Configuration: Customize mount points and static file prefixes
• Django Views: Serve documentation through Django's URL routing
• Image Support: Images in markdown are served via Django's static files

Installation

pip install mkdocs-django

Quick Start

1. Add mkdocs_django to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ... other apps
    'django.contrib.staticfiles',
    'mkdocs_django',
]

2. Add the custom staticfiles finder to your settings:

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'mkdocs_django.finders.MkDocsFinder',
]

3. Configure MkDocs settings (optional):

# Path to your mkdocs.yml file (default: 'mkdocs.yml')
MKDOCS_CONFIG_PATH = 'path/to/mkdocs.yml'

# URL mount point for documentation (default: '/docs/')
MKDOCS_MOUNT_POINT = '/docs/'

# Static files prefix for documentation (default: 'docs/')
MKDOCS_STATIC_PREFIX = 'docs/'

4. Include the URLs in your project:

from django.urls import include, path

urlpatterns = [
    # ... other patterns
    path('docs/', include('mkdocs_django.urls')),
]

5. Create your MkDocs configuration file (mkdocs.yml):

site_name: My Documentation
nav:
  - Home: index.md
  - About: about.md
theme:
  name: readthedocs

6. Create your documentation in the docs/ directory:

mkdir -p docs
echo "# Welcome" > docs/index.md
echo "# About" > docs/about.md

Usage

Serving Documentation During Development

The documentation will be automatically built when you access the documentation URL (e.g., /docs/). The first request will trigger a build, and subsequent requests will be cached.

Collecting Static Files for Production

When you run collectstatic, the MkDocs finder will build your documentation and include all generated files:

python manage.py collectstatic

This will:

1. Build your MkDocs documentation
2. Copy all generated HTML, CSS, JavaScript, and images to your static files directory
3. Prefix all files with the configured MKDOCS_STATIC_PREFIX

Manual Documentation Build

You can manually build the documentation using the management command:

python manage.py build_docs

Or with the --clean flag to clean the site directory first:

python manage.py build_docs --clean

How It Works

Integration with Django Staticfiles

The integration works through a custom staticfiles finder (MkDocsFinder) that:

1. Detects when static files are being collected
2. Triggers an MkDocs build using the Python API
3. Makes the generated files available to Django's staticfiles system
4. Prefixes all documentation files for organization

Documentation Views

The DocumentationView serves the built documentation:

• Handles requests to documentation URLs
• Builds documentation on first access
• Caches responses for performance
• Serves all file types (HTML, CSS, JavaScript, images)
• Provides security checks to prevent path traversal

Images and Assets

Images referenced in your markdown files are automatically handled:

![Example Image](img/example.png)

These will be:

1. Processed by MkDocs during the build
2. Included in the staticfiles collection
3. Served via Django's static files system

Configuration Reference

Settings

• MKDOCS_CONFIG_PATH (default: 'mkdocs.yml')

  • Path to your MkDocs configuration file
  • Can be absolute or relative to project root

• MKDOCS_MOUNT_POINT (default: '/docs/')

  • URL path where documentation will be served
  • Used for URL configuration

• MKDOCS_STATIC_PREFIX (default: 'docs/')

  • Prefix for documentation static files
  • Helps organize static files in deployment

URL Configuration

Include the documentation URLs at your desired mount point:

urlpatterns = [
    path('documentation/', include('mkdocs_django.urls')),  # Custom mount point
]

Testing

The package includes a comprehensive test suite:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mkdocs_django

Example Project

See the tests/testproject directory for a complete example Django project with mkdocs-django configured.

Requirements

• Python >= 3.11
• Django >= 4.2
• MkDocs >= 1.5

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, testing guidelines, and the pull request process.

Development

This project uses uv for fast Python package management:

# Clone and setup
git clone https://github.com/goodtune/mkdocs-django.git
cd mkdocs-django
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ --cov=mkdocs_django --cov-report=term-missing

# Run linting
uv run ruff check mkdocs_django/ tests/

Continuous Integration

This project uses GitHub Actions to test against multiple Python (3.11, 3.12, 3.13) and Django (4.2, 5.2) versions on every pull request.