Settings#

All configuration is ordinary Django settings. mdjango reads them on every request through mdjango.conf.get_conf(), so there is no restart to pick up a change under runserver. MDJANGO_CONTENT_DIR is required. Everything else has a default. The Theme's colours and type are set in CSS (theme tokens), not here — the one setting that touches them, MDJANGO_EXTRA_CSS, only loads your stylesheet; it carries no values.

Content#

Setting	Type	Default	Effect
`MDJANGO_CONTENT_DIR`	`str` or `Path`	required	Root of the Content tree.
`MDJANGO_INCLUDE_DRAFTS`	`bool`	`DEBUG`	Include Pages marked `draft: true` in the registry, and so in navigation, search, the LLM artifacts and the export.
`MDJANGO_ALWAYS_REBUILD`	`bool`	`DEBUG`	Re-read the Content tree and rebuild the search index and LLM artifacts on every request. Also disables response caching.

Shell#

Setting	Type	Default	Effect
`MDJANGO_BRAND`	`str`	`"docs"`	Wordmark text in the header. Fallback for `<title>`.
`MDJANGO_SITE_TITLE`	`str`	`""`	`<title>`, and the `#` heading of `llms.txt` and `llms-full.txt`. Falls back to `MDJANGO_BRAND`.
`MDJANGO_HOME_URL`	`str`	`"/"`	Target of the wordmark link.
`MDJANGO_VERSION`	`str`	`""`	Display string rendered as a chip in the header. Hidden when empty. Not used for routing.
`MDJANGO_GITHUB_URL`	`str`	`""`	Renders a header link labelled `github`. Hidden when empty.
`MDJANGO_HEADER_LINKS`	iterable of `{"label": str, "url": str}` dicts or `mdjango.conf.HeaderLink`	`()`	Extra header links, in order, between the `llms.txt` links and the GitHub link.
`MDJANGO_EXTRA_CSS`	`str` or iterable of `str`	`()`	Stylesheet `{% static %}` name(s), linked after mdjango's own sheet — the supported way to override the seven CSS seeds without shadowing a template. A string is one file; an iterable is several, in order. See Change the colours and type.
`MDJANGO_ASSET_EXTENSIONS`	iterable of `str`	`png jpg jpeg gif svg webp`	Non-markdown file extensions served as assets from the Content tree (case-insensitive, leading dot optional). Defaults to images; set it to widen (e.g. add `pdf`) or narrow what a page can reference beside itself.

LLM artifacts#

Setting	Type	Default	Effect
`MDJANGO_LLM_DOCS`	`bool`	`True`	Master switch for the `llms.txt`, `llms-full.txt`, `index.md` and per-page `.md` routes, the header and drawer links, the `<link rel="alternate">`, and the export of those files. `False` returns 404 from all four routes. Search is unaffected.
`MDJANGO_DESCRIPTION`	`str`	`""`	One-line summary rendered as a `>` blockquote under the title in `llms.txt` and `llms-full.txt`.

Caching#

Setting	Type	Default	Effect
`MDJANGO_CACHE_SECONDS`	`int`	`300`	TTL of the server-side page cache (Django's default cache backend, key `mdjango:page:<path>`, `@index` for the Index page) and the value of `Cache-Control: public, max-age=`. `0` disables the page cache and sets `Cache-Control: no-cache`. Ignored while `MDJANGO_ALWAYS_REBUILD` is true. An `ETag` is always emitted.

Validation#

Nothing is checked at startup. There are no Django system checks. A wrong value surfaces on the first request, as a 500 in a running site or as an error from mdjango_build.

Fault	Raised
`MDJANGO_CONTENT_DIR` missing or empty	`django.core.exceptions.ImproperlyConfigured`
`MDJANGO_CONTENT_DIR` is not a directory	`mdjango.features.common.exceptions.ContentError`
a `MDJANGO_HEADER_LINKS` dict without `label` or `url`	`KeyError`
`MDJANGO_EXTRA_CSS` neither a string nor an iterable of them	`TypeError`
`MDJANGO_CACHE_SECONDS` not convertible with `int()`	`ValueError` or `TypeError`

Not settings#

INSTALLED_APPS must contain "django_cotton" and "mdjango". "django.contrib.staticfiles" is needed to serve the Shell's assets. Order between the two apps does not matter.
STATIC_URL is used by mdjango_build as the prefix of the exported static directory.
There is no setting for the maximum tree depth (fixed at three), for disabling search, for the markdown extensions, for a canonical URL, or for a logo. (A stylesheet does have one now — MDJANGO_EXTRA_CSS, above.)
There is no setting for analytics or other <head> scripts — a setting cannot safely carry raw markup. Inject them through the head slot instead; see Add analytics and other head tags.
There is no base-URL or domain setting. mdjango emits root-relative URLs, so it stays portable across mount prefixes. The sitemap needs absolute URLs, so it derives the domain from the request at runtime, or from the mdjango_build --base-url flag for the static export — never a setting. See Make your docs discoverable.