Astro Theme Dahlia
A minimal, content-first documentation theme
Dahlia is an installable documentation theme for Astro 7. It provides the features expected from a modern docs site—routing, navigation, search, internationalization, MDX components, Expressive Code, Mermaid, and dark mode—but arranges them around a quieter reading experience.
It is not a recolored Lotus. Dahlia exists to test a stronger idea: two themes can share an author contract and still make meaningfully different decisions about layout, density, and visual rhythm.
Familiar content, different composition
Dahlia uses a persistent left navigation, a centered article column, and a sticky table of contents on wider screens. The page chrome stays restrained so long guides and references remain the visual center of the product.
Content first
The article column sets the rhythm. Navigation and metadata support it without competing for attention.
Complete shell
Search, i18n-aware routes, code rendering, Mermaid, mobile navigation, and dark mode are included rather than left to each starter.
Shared vocabulary
The same callouts, cards, tabs, steps, and file trees used in Lotus work in Dahlia without changing the MDX.
Shared infrastructure without a shared identity
The theme consumes @prosefly/astro-components and follows the same broad collection contract as
Lotus. Dahlia then maps the shared semantic tokens into its own palette and owns its navigation
shell, typography, spacing, and responsive composition.
This division avoids two common outcomes: duplicating every interactive component in a second theme, or building one highly conditional base theme whose internals are difficult to reason about.
The boundary is visible in the dependency graph
Dahlia depends on the shared component package. The component package has no Dahlia-specific branch, stylesheet, or import.
A maintained path to a working site
- Create a project from the Dahlia starter.
- Describe the product and navigation in
theme.config.json. - Add documents to the Astro
docscollection. - Customize the semantic tokens or override a shell component only when the product needs it.
The maintained starter is useful here: it demonstrates the intended package boundaries without making the starter itself the framework. Existing Astro sites can install and register Dahlia directly.
Read the Dahlia documentation, learn how it was separated from Lotus, or browse the source.
Writing from Astro Theme Dahlia
Decisions, implementation notes, and lessons from the work.