mdjango
v0.1.0rc2.dev3+g175c8392a llms.txtllms-full.txt github

Getting started

Install and mount#

This tutorial takes an existing Django project from nothing to a rendered documentation page served by your own runserver. It follows one path and skips every option. The how-to pages cover those.

You need: a Django 5.2+ project on Python 3.11+ with the default startproject settings: django.contrib.staticfiles in INSTALLED_APPS and APP_DIRS: True in TEMPLATES. mdjango adds no database tables, so there are no migrations to run.

1. Install the package#

pip install mdjango

The package depends on Django, Markdown, pymdown-extensions, Pygments and django-cotton.

2. Register the apps#

# settings.py
INSTALLED_APPS = [
    # ...
    "django.contrib.staticfiles",
    "django_cotton",
    "mdjango",
]

Both apps are required. mdjango's templates are cotton components, and listing django_cotton installs the template loader that compiles them.

3. Point mdjango at a content directory#

# settings.py
MDJANGO_CONTENT_DIR = BASE_DIR / "content"
MDJANGO_BRAND = "acme"

MDJANGO_CONTENT_DIR is the only required setting. MDJANGO_BRAND is the wordmark in the header. Without it the site calls itself "docs".

4. Include the URLs#

# urls.py
from django.urls import include, path

urlpatterns = [
    # ...
    path("docs/", include("mdjango.urls")),
]

To serve the docs at the site root instead (when the whole site is documentation), mount at "" — see Serve the docs at the site root.

5. Write two pages#

mkdir -p content/guides

<!-- content/_index.md -->
---
title: Acme docs
---

# Acme docs

Welcome. Start with the [first guide](guides/first-guide/).

<!-- content/guides/first-guide.md -->
---
title: First guide
---

# First guide

## Install

Run the installer.

```bash
acme install
```

## Verify

Run `acme --version`.

6. Run the server and open the site#

python manage.py runserver

Open http://127.0.0.1:8000/docs/. You see your Index page with acme as the wordmark, a left navigation holding a pinned Acme docs link and a Guides section, and the link to your first guide. Click it. The page renders with an "On this page" table of contents built from the two ## headings, a copy button on the code block, and prev/next links at the bottom. Press / to open search and type installer. The guide is found by its body text.

Edit first-guide.md and reload. With DEBUG = True the content is re-read on every request, so the change is already there.

Where next#