Aurora — an MkDocs theme

The Oduist brand applied to MkDocs: the "Aurora" palette in both schemes, module-scoped navigation for aggregated monorepo sites, and search built on a vendored lunr over the index the stock search plugin already emits.

Extracted from oduist/connect_addons_ng, where it grew as an in-repo theme. See specs/docs_site.md in that repository for the design and the decision behind it (ADR-050).

Using it

Install the theme, then name it in the site's mkdocs.yml:

theme:
  name: aurora
  logo: assets/img/logo.png      # the Oduist mark, shipped with the theme
  favicon: assets/img/logo.png

Nothing else is required — no extra_css, no extra_javascript, no build step in the site. The theme renders extra_css and extra_javascript after its own assets, so a site keeps its page-specific styling to itself.

The theme provides: the page skeleton and both colour schemes, header with search and scheme toggle, a sidebar narrowed to the module being read, the sticky breadcrumb trail, the table of contents with its scrollspy, prose typography and Pygments colours, five admonition types, tables, tabs, the search dialog, the footer pager and the "Edit on GitHub" link.

Image zoom. Every content image at least 200px wide becomes clickable and opens at full size in a modal <dialog>; hovering dims it and shows a magnifier. Images inside a link are left alone, and an author can opt one out with data-no-zoom. Documentation is mostly screenshots of interfaces that render at half size in a content column — this is what makes them readable.

The home page kit

Beyond generic chrome the theme carries a component kit for an Oduist docs front page: the hero, the primary/secondary buttons and the "periodic table" of modules with its category filter and tooltips (assets/js/module-table.js), plus the Oduist mark in assets/img/.

These are not generic. The markup lives in a site's own index.md, so the class names — hero-*, mod-*, docs-button* — are part of this theme's public surface rather than private detail: renaming one breaks a site that cannot see this repository. The kit sits here because both repositories are Oduist's and keeping the front page's pieces together beat splitting them across a repository boundary; a theme meant for a third party would not carry them.

Working on it

The stylesheet is built from theme-src/app.css with the Tailwind CLI:

npm install
npm run watch:css     # or: npm run build:css

mkdocs_theme_aurora/assets/app.css is a build artifact and is committed — a site installing the theme gets the compiled stylesheet and needs no Node. Rebuild it and commit the result with any change under theme-src/.

To preview a change against a real site, install the theme into that site's environment in editable mode:

pip install -e /path/to/mkdocs-theme-aurora
mkdocs serve

Template edits show up on reload; stylesheet edits need npm run watch:css running alongside.

Notes for the next person

• The .prose token remap in theme-src/app.css is deliberately unlayered. @tailwindcss/typography emits its defaults into @layer utilities, which outranks @layer components regardless of specificity, so a remap written in the components layer silently loses.
• Tailwind scans only what the @source directives name. A class used in a file outside them is dropped from the build without warning.
• The header and the breadcrumb trail share one sticky surface (.docs-topbar). They were two, and their offsets had to agree by hand — which they stopped doing the moment the type scale changed the header's height.