Overview - Dahlia

Dahlia is an installable documentation theme for Astro v7, Tailwind CSS v4, and MDX. It provides the page shell, docs route, navigation model, theme tokens, and shared MDX components needed to start a project documentation site without rebuilding the chrome from scratch.

What Dahlia includes

Docs shell

Render a full-height left navigation rail, right-side article layout with TOC, page metadata, mobile docs menu, and footer from theme configuration.

Routing

Generate docs pages, Markdown source routes, search indexes, localized URLs, and route-prefixed docs from Astro content collection entries.

Use the built-in client-side search dialog and generated JSON index, or replace the search UI with a component override.

Design tokens

Configure accent colors, gray scales, radius, color mode, fonts, and lower level CSS tokens for deeper styling control.

MDX components

Compose pages with callouts, cards, steps, tabs, accordions, file trees, badges, media, embeds, and Iconify icons.

Overrides

Replace shell slots such as search, navbar, page header, page actions, contributors, and previous or next navigation when configuration is not enough.

The four parts of a Dahlia site

astro.config.ts registers the Dahlia integration.
src/content.config.ts defines a docs collection with Dahlia’s loader and schema.
theme.config.json controls identity, routes, navigation, search, source links, appearance, and component overrides.
src/content/docs/**/*.mdx contains the documentation pages.

Dahlia reads the collection and injects page, Markdown source, and search routes under docsBase. With the default docsBase: '/', it generates:

/ and nested docs pages
/*.md Markdown source routes
/search.json search index data

The docsNav config decides which sidebar and subnav section owns each page. For locale directories, route prefixes, and fallback behavior, see Internationalization. For loader base, docsBase, and slug behavior, see Content Routing.

First steps

Install the theme.

Add Dahlia, then register the integration in astro.config.ts. Install @prosefly/astro-components directly when your own content imports shared MDX components.

Install Dahlia
Configure routes and locales.

Decide where docs are mounted and how localized content directories map to public URLs.

Review content routing
Build the docs shell.

Set project identity, appearance, site nav links, docs navigation, footer links, page actions, and search behavior.

Configure the project
Write content.

Add frontmatter, Markdown, images, code blocks, and shared MDX components to replace the demo pages with project documentation.

Review authoring essentials
Customize when configuration is not enough.

Use CSS tokens for visual changes and component overrides for shell markup or behavior changes.

Customize Dahlia