Metadata-Version: 2.4
Name: django-site-documentation
Version: 1.0.0
Summary: A reusable Django app providing a structured documentation system (Library > Shelf > Book > Chapter > Page) served on a dedicated URL path (or optionally a subdomain), rendering content from .md files within each Django app.
Author-email: Lucas Kopsch <kopschlucas@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/lkopsch/django-site-documentation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=5.2.14
Requires-Dist: Markdown>=3.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: django-ratelimit>=4.1
Dynamic: license-file

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

```python
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:
   ```bash
   pip install django-site-documentation
   ```

2. Add to `INSTALLED_APPS`:
   ```python
   INSTALLED_APPS = [
       ...
       'django_site_documentation',
   ]
   ```

3. Configure the documentation URL in `settings.py`:
   ```python
   DOCUMENTATION_DOMAIN = 'localhost:8000/doc'
   ```

4. Add the middleware **after** `SessionMiddleware` and `AuthenticationMiddleware`:
   ```python
   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):
   ```python
   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:

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

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