# Overview

Learn what Dahlia provides and how the documentation theme is organized.

import { Card, CardGrid, Steps } from '@prosefly/astro-components';

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

<CardGrid>
  <Card icon="lucide:layout-template" title="Docs shell" href="/docs/configuration/project/">
    Render a full-height left navigation rail, right-side article layout with
    TOC, page metadata, mobile docs menu, and footer from theme configuration.
  </Card>
  <Card icon="lucide:route" title="Routing" href="/docs/configuration/content-routing/">
    Generate docs pages, Markdown source routes, search indexes, localized URLs,
    and route-prefixed docs from Astro content collection entries.
  </Card>
  <Card icon="lucide:search" title="Search" href="/docs/configuration/search/">
    Use the built-in client-side search dialog and generated JSON index, or
    replace the search UI with a component override.
  </Card>
  <Card icon="lucide:palette" title="Design tokens" href="/docs/configuration/appearance/">
    Configure accent colors, gray scales, radius, color mode, fonts, and lower
    level CSS tokens for deeper styling control.
  </Card>
  <Card icon="lucide:blocks" title="MDX components" href="/docs/components/callout/">
    Compose pages with callouts, cards, steps, tabs, accordions, file trees,
    badges, media, embeds, and Iconify icons.
  </Card>
  <Card icon="lucide:replace" title="Overrides" href="/docs/customization/overriding-components/">
    Replace shell slots such as search, navbar, page header, page actions,
    contributors, and previous or next navigation when configuration is not
    enough.
  </Card>
</CardGrid>

## The four parts of a Dahlia site

1. `astro.config.ts` registers the Dahlia integration.
2. `src/content.config.ts` defines a `docs` collection with Dahlia's loader and
   schema.
3. `theme.config.json` controls identity, routes, navigation, search, source
   links, appearance, and component overrides.
4. `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](/docs/configuration/i18n/). For loader base, docsBase,
and slug behavior, see [Content Routing](/docs/configuration/content-routing/).

## First steps

<Steps>

1. **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](/docs/installation/)

2. **Configure routes and locales.**

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

   [Review content routing](/docs/configuration/content-routing/)

3. **Build the docs shell.**

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

   [Configure the project](/docs/configuration/project/)

4. **Write content.**

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

   [Review authoring essentials](/docs/essentials/frontmatter/)

5. **Customize when configuration is not enough.**

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

   [Customize Dahlia](/docs/customization/css-styling/)

</Steps>