Content tree rules#

The Content tree is the directory MDJANGO_CONTENT_DIR points at. It is the only source of content. There is no database, no admin and no registration step.

Layout#

• A directory inside a Subsection raises ContentError. There is no fourth level.
• Only .md files are read. Other files are ignored and nothing is copied to the export.
• Directories are walked in filename order, then sorted by weight.

Index files#

Recognised stems: _index and index. A file named index.md inside a Section or Subsection is treated as that group's index file: its body is discarded and it gets no URL. Name a Page anything else.

The root _index.md ignores draft. It is read unconditionally. A Section or Subsection with no index file takes its title from the humanised directory name (- and _ become spaces, first letter capitalised, the rest lower-cased) and weight 100.

Front-matter#

A leading block fenced by lines that are exactly ---. Each line is split on its first :. The key is lower-cased and stripped. The value is stripped of whitespace and of surrounding ' or ". Lines without a colon are skipped. No YAML: no lists, no nesting, no multi-line values. A block without a closing --- is treated as body. Unknown keys are ignored.

The first-heading fallback matches a # line with up to three leading spaces and optional closing #s.

Ordering#

Siblings sort by (weight, title.lower()), lowest weight first, regardless of kind: Pages, Subsections and Sections in the same parent share one sequence. A run of consecutive Loose pages at the root renders as one untitled navigation group at its position and as a ## Documentation heading in llms.txt.

Previous/next links follow the flattened navigation order across Section and Subsection boundaries. The Index page is not part of that order.

Visibility#

• A Page with draft: true is omitted unless MDJANGO_INCLUDE_DRAFTS is true.
• A Section or Subsection with no visible Pages is omitted from navigation, search, llms.txt and the export. This is not an error.

Slugs and URLs#

Slugs come from Django's slugify applied to the filename stem (Pages) or directory name (groups). slugify lower-cases, so Hello.md and hello.md collide.

Sections and Subsections have no URL. Each Page also has a markdown alternate at the same path with .md in place of the trailing slash (/<mount>/how-to/deploy.md; the Index page at /<mount>/index.md).

Errors#

All are mdjango.features.common.exceptions.ContentError, raised when the registry is built. In a running site that is the first request after a process start. No view catches it, so the request returns a 500. mdjango_build catches it and exits with the message.