django-site-documentation

A reusable Django application that provides a structured documentation system served on a dedicated URL path (or optionally a subdomain). Content is rendered from .md files located within each Django app's directory.

Security Requirements

When deploying this application in production, the following settings must be configured:

• SESSION_COOKIE_SECURE = True — ensures session cookie is only sent over HTTPS.
• CSRF_COOKIE_SECURE = True — ensures CSRF cookie is only sent over HTTPS.
• SESSION_COOKIE_HTTPONLY = True — prevents JavaScript access to the session cookie.
• SECURE_HSTS_SECONDS = 31536000 — enables HTTP Strict Transport Security (start with a lower value during rollout).
• SECURE_SSL_REDIRECT = True — redirects all HTTP traffic to HTTPS.
• SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') — required when behind a reverse proxy.

Additionally, add django_site_documentation.middleware.ContentSecurityPolicyMiddleware to your MIDDLEWARE list (after SecurityMiddleware) to enable Content Security Policy headers:

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    ...
    'django_site_documentation.middleware.ContentSecurityPolicyMiddleware',
]

Concepts

• Library: The entire documentation site
• Shelf: A Django app that contains documentation
• Chapter: A folder inside django-doc/
• Page: A .md file inside a chapter folder

Quick Start

1. Install the package:

   pip install django-site-documentation
   

2. Add to INSTALLED_APPS:

   INSTALLED_APPS = [
       ...
       'django_site_documentation',
   ]
   

3. Configure the documentation URL in settings.py:

   DOCUMENTATION_DOMAIN = 'localhost:8000/doc'
   

4. Add the middleware after SessionMiddleware and AuthenticationMiddleware:

   MIDDLEWARE = [
       'django.contrib.sessions.middleware.SessionMiddleware',
       'django.contrib.auth.middleware.AuthenticationMiddleware',
       ...
       'django_site_documentation.middleware.DocumentationDomainMiddleware',
   ]
   

5. Login directly on the documentation URL — the app includes its own login/logout views at localhost:8000/doc/login/. Just make sure your user is a superuser to access edit features.

6. Add the documentation URL to ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS (no subdomains needed):

   ALLOWED_HOSTS = [
       'example.com',
       'localhost',          # local development
   ]
   CSRF_TRUSTED_ORIGINS = [
       'https://example.com',
       'http://localhost:8000',  # dev
   ]
   

7. Create documentation in any installed app:

   yourapp/
   └── django-doc/
       ├── getting-started/
       │   ├── index.md
       │   └── installation.md
       └── guides/
           └── advanced-usage.md
   

Frontmatter

Each .md file can include YAML frontmatter for metadata:

---
title: My Page Title
order: 1
---

Chapters can use an index.md file to set chapter-level metadata.