Why the house style is fixed#
mdjango ships exactly one Theme. You can change its colours, its typeface and its size. You cannot change its layout, its chrome or its personality. This is deliberate, and this page lays out the trade.
The drop-in promise#
The point of mdjango is that installing it into a project gives that project a finished documentation site. A neutral, fully themeable base would hand back the work it exists to remove: choosing a type scale, tuning a palette, designing a sidebar. So the House style, flat, monochrome, typographic, one layout, is fixed, and adopting mdjango means adopting it.
Two ramps, set by their ends#
What is open is the Override surface: the two ends of each colour Ramp, an accent, the font and the base size. Seven CSS custom properties.
The interior stops of each Ramp (raised surfaces, body text, muted text) are Derived values, computed from the ends and locked. That is what makes the surface safe: you cannot pick a body-text colour that fails against your background, because you do not pick it. The ladder is computed from the two colours you did pick.
The derivation mixes within a Ramp, never across the palette. An earlier model mixed text toward the background, which averaged away the chroma of any tinted palette and shipped visibly greyer than its design. Giving each Ramp its own two ends fixed that, and the exposed set grew from five tokens to seven as a result.
Those seven names are a public API. Renaming or dropping one is a breaking change and is versioned as one. The markup of the templates, their class names and their context keys are not part of that promise, and mdjango may change them in any release.
The shell is included, not extended#
mdjango renders the whole page from your settings: header, navigation, article, table of contents,
prev/next. That is the product. There is no {% block %} to fill, no slot for extra chrome, no
plugin point for a footer or a logo. A block contract would freeze the markup into a public API and
take away the freedom to improve the Shell; a partial extension point would produce sites that are
half House style and half something else. A project that needs different chrome has outgrown
mdjango and should fork it.
Overriding the seeds is the exception, and it stays outside that markup: MDJANGO_EXTRA_CSS loads
your stylesheet after the Shell's own, so you re-colour and re-type the House style without touching
a template. Change the colours and type shows it.
No build step, no CDN#
Everything the Shell needs ships in the wheel: a precompiled stylesheet, vendored Stimulus and
MiniSearch, six woff2 faces of the default font. A reusable app cannot assume the project has
Node, a bundler, network access at page load, or a permissive content-security policy. A font that
only sometimes arrives is not a House style.
For the same reason there are no utility classes. The package ships tokens and semantic classes,
and a Consumer's own pages can reuse the font through fonts.css.
What you give up#
- A different layout, a card-based or bordered restyle, an independent border hue, a logo in the header: not reachable. mdjango is the wrong tool if you need them.
- A proportional body face is reachable through
--font. Code stays monospace. - A configurable navigation depth: rejected, because it would let a project configure its way into a sidebar the Shell cannot render legibly. See Why three levels.