mdjango Brings One-Command Documentation Sites to Django Projects
Django developers who need technical documentation for their projects have a new option that trades flexibility for speed. mdjango is a Django app that turns a directory of Markdown files into a fully functional documentation site with navigation, search, dark mode, and machine-readable artifacts for AI tools. The trade-off is deliberate: you get a working docs site in about 30 minutes, but you give up the ability to extensively customize the layout and design.
The project positions itself between two extremes. On one side are full documentation frameworks like Sphinx or MkDocs that require dedicated configuration and often live outside your Django deployment. On the other side are hand-rolled documentation pages built into Django projects, which give you full control but take significant time to get right. mdjango sits in the middle: you install it, point it at your Markdown files, and get a production-ready docs site that lives inside your existing Django process.
What You Get Out of the Box
mdjango serves a documentation site at whatever URL prefix you configure. The default feature set covers what most technical documentation needs: a header with site branding, section navigation on the side, the article content itself, a table of contents for long pages, and prev/next links between pages. Full-text search works across all your Markdown files. Dark mode is built in, not an afterthought.
One notable addition is support for the llms.txt family of machine-readable artifacts. These are structured files that AI tools can consume to understand your documentation's content and structure. As more developers build workflows around AI-assisted coding, having your documentation machine-readable by default is a practical advantage.
Every page in the rendered site has a .md alternate linked from the header. Readers can switch between the formatted HTML view and the raw Markdown source at any time. This is useful for developers who want to copy code examples or contribute corrections to the source files.
The House Style Philosophy
mdjango enforces a single design system it calls the House style. You configure two colour ramps (a start and end colour for gradients), an accent colour, a font, and a base size. From those inputs, the framework derives the entire visual layout and remaining palette. You cannot override the layout, spacing, or component structure.
This is the core design trade-off, and mdjango is explicit about it. The project's documentation states that if you need more customization, you are better off building your own docs feature in your Django app or using a different tool. mdjango is designed for teams that want working documentation fast and are willing to accept a fixed visual identity to get it.
For many internal documentation sites, developer portals, or project READMEs that need more than a single page, this constraint is a feature rather than a limitation. The 30-minute setup claim is credible precisely because there are no layout decisions to make. You pick your colours and font, and the system handles the rest.
Integration With Django's Existing Infrastructure
Because mdjango runs inside your Django process, it inherits whatever middleware, authentication, and deployment setup your project already has. If your Django app uses session-based authentication, you can protect documentation pages behind the same login. If you deploy with Gunicorn behind Nginx, the docs site deploys with the rest of your application. There is no separate build step or deployment pipeline to manage.
You can also use mdjango as part of a larger Django application rather than as a standalone documentation site. The app mounts at a configurable URL prefix, so it can sit alongside admin panels, API endpoints, and other Django views without conflict. The reference section of the documentation lists every route the app registers, making it straightforward to understand how it fits into your URL configuration.
For teams that do want to decouple documentation from the Django process, mdjango includes a static site export feature. This writes the same rendered site to a directory as plain HTML files, which you can host on any static file server or CDN. The static export produces identical output to the dynamically served version, so you can start with Django serving and migrate to static hosting later without changing your content or authoring workflow.
Content Authoring and Structure
Your documentation lives in a directory of Markdown files that mdjango calls the Content tree. The framework reads these files, applies front-matter metadata, and renders them into the navigation structure. You organize files into sections and subsections, and mdjango derives the table of contents and section navigation from the directory layout.
Front-matter keys control page-level settings like titles, descriptions, and ordering. The reference section of the documentation lists every supported front-matter key. The explanation section covers the design decisions behind the content structure, which is useful if you need to understand why certain organizational patterns work better than others with the framework.
When DEBUG is off in your Django settings, mdjango adjusts its caching and draft visibility behaviour. Pages marked as drafts in their front-matter are hidden from the rendered site in production. Static assets are cached aggressively. These are the kinds of operational details that matter when you move from development to deployment, and mdjango handles them automatically based on your Django configuration.
Who This Is For
mdjango makes the most sense for Django teams that need documentation but don't want to maintain a separate documentation system. If your project already runs on Django and you have Markdown files describing your API, your architecture, or your setup procedures, mdjango gives you a fast path from those files to a usable docs site.
It is less suited to projects that need highly customized documentation layouts, multi-language support, or complex publishing workflows. The House style constraint is real, and teams that need visual integration with a broader design system will find it limiting. For those cases, a dedicated documentation tool or a custom Django view is still the better choice.
The project is open source and self-documenting: the site you browse at mdjango.chesselink.com is the framework running with no overrides, showing exactly what you get out of the box. Every page's Markdown source is available for inspection, which makes evaluating the framework as straightforward as reading its own docs.