Installation

Start from the Dahlia starter template for a new documentation site, or install Dahlia manually when you already have an Astro project.

Starter Template

Use the starter when you want the fastest path to a working site.

pnpm create astro@latest my-docs --template prosefly/astro-template-dahlia-starter
cd my-docs
pnpm dev

The template source is available at prosefly/astro-template-dahlia-starter.

After the site is running, replace the example content and update the Dahlia theme config with your project name, navigation, sidebar structure, appearance, footer, and source repository.

Manual Setup

Use manual setup when your project already exists or when you want to introduce Dahlia one piece at a time.

1. Install Dahlia.

   Add the theme package to your Astro project.

   pnpm add @prosefly/astro-theme-dahlia

   Install @prosefly/astro-components directly when your own MDX or Astro files import shared components such as cards, steps, tabs, callouts, badges, or file trees.

   pnpm add @prosefly/astro-components

2. Register the integration.

   Configure Astro with the Dahlia integration.

   import { defineConfig } from 'astro/config';
   import dahlia from '@prosefly/astro-theme-dahlia';
   
   export default defineConfig({
     integrations: [dahlia()],
   });

3. Create the theme config.

   Start with project identity and a minimal sidebar.

   {
     "$schema": "https://astro-theme-dahlia.prosefly.dev/schema.json",
     "name": "My Docs",
     "description": "Documentation for my project.",
     "siteNav": [{ "label": "Docs", "href": "/" }],
     "docsNav": [
       {
         "label": "Guides",
         "icon": "lucide:rocket",
         "items": ["index"]
       }
     ]
   }

   Set docsBase: '/docs' when the Astro project already has a site home page and docs should live under /docs/.

   Pass options directly to dahlia({...}) in astro.config.ts when you need TypeScript, imports, or dynamic values. Those options override values from theme.config.json.

4. Register the docs collection.

   Create src/content.config.ts and use the loader and schema from Dahlia.

   import { defineCollection } from 'astro:content';
   import { docsLoader, docsSchema } from '@prosefly/astro-theme-dahlia/content';
   
   const docs = defineCollection({
     loader: docsLoader(),
     schema: docsSchema(),
   });
   
   export const collections = { docs };

5. Add the first docs page.

   Dahlia reads from src/content/docs by default.

   ---
   title: Overview
   description: Start here.
   ---
   
   Welcome to the docs.

6. Start development.

   pnpm dev

Next Steps

• Review Project Configuration to define the site identity, navigation, docs navigation, footer, and source repository.
• Review Content Routing before moving docs under a route prefix or changing the docs loader base.
• Run pnpm check before shipping changes. It validates content collections, MDX imports, Astro components, and TypeScript.