mkdocs-django 0.1.0
A reusable Django application that will serve your documentation within a Django project.
Requires Python: >=3.11

# mkdocs-django

[![Test](https://github.com/goodtune/mkdocs-django/actions/workflows/test.yml/badge.svg)](https://github.com/goodtune/mkdocs-django/actions/workflows/test.yml)
[![PyPI version](https://badge.fury.io/py/mkdocs-django.svg)](https://badge.fury.io/py/mkdocs-django)
[![Python Versions](https://img.shields.io/pypi/pyversions/mkdocs-django.svg)](https://pypi.org/project/mkdocs-django/)
[![Django Versions](https://img.shields.io/badge/django-4.2%20%7C%205.2-blue.svg)](https://www.djangoproject.com/)

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

```bash
pip install mkdocs-django
```

## Quick Start

1. Add `mkdocs_django` to your `INSTALLED_APPS`:

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

2. Add the custom staticfiles finder to your settings:

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

3. Configure MkDocs settings (optional):

```python
# 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:

```python
from django.urls import include, path

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

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

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

6. Create your documentation in the `docs/` directory:

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

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

```bash
python manage.py build_docs
```

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

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

```markdown
![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:

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

## Testing

The package includes a comprehensive test suite:

```bash
# 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](CONTRIBUTING.md) for development setup, testing guidelines, and the pull request process.

### Development

This project uses [uv](https://github.com/astral-sh/uv) for fast Python package management:

```bash
# 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.