Install Dahlia

Use the starter template for a new documentation site. Follow the manual setup when adding Dahlia to an existing Astro project or when you want to understand every required file.

Starter template

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

The template is maintained at prosefly/astro-template-dahlia-starter. After it starts, update theme.config.json and replace the example files under src/content/docs.

Manual setup

This path starts with an Astro project and ends with a working Dahlia site at http://localhost:4321/. If you do not have an Astro project yet, create one:

pnpm create astro@latest my-docs
cd my-docs

1. Install Dahlia.

   pnpm add @prosefly/astro-theme-dahlia

   Dahlia includes the integrations it needs. Install @prosefly/astro-components separately when your own MDX files import shared components or when astro.config.ts customizes its integration.

   pnpm add @prosefly/astro-components

2. Register the integration.

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

3. Register the docs collection.

   Create src/content.config.ts:

   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 };

4. Add a minimal theme config.

   Create theme.config.json in the project root:

   {
     "$schema": "https://prosefly.dev/schema/dahlia.json",
     "name": "Acme Docs",
     "description": "Documentation for Acme.",
     "docsNav": [
       {
         "label": "Guide",
         "icon": "lucide:book-open",
         "items": ["index"]
       }
     ]
   }

5. Create the first page.

   ---
   title: Overview
   description: Learn how to use Acme.
   ---
   
   Welcome to the Acme documentation.

6. Start the development server.

   pnpm dev

   Open http://localhost:4321/. You should see the Overview page and a Guide section in the sidebar.

Add another page

Create src/content/docs/getting-started.mdx:

---
title: Getting Started
sidebar:
  icon: "lucide:rocket"
---

Your first task goes here.

Then add its content entry ID to docsNav:

{
  "label": "Guide",
  "items": ["index", "getting-started"]
}

The content entry ID is the path below src/content/docs without the .mdx extension. Nested files use slash-separated IDs such as configuration/authentication.

Put docs under /docs

The minimal setup serves documentation from /. For a product site with a separate homepage, set docsBase and update the site navigation:

{
  "name": "Acme",
  "docsBase": "/docs",
  "siteNav": [
    { "label": "Home", "href": "/" },
    { "label": "Docs", "href": "/docs/" }
  ],
  "docsNav": [
    { "label": "Guide", "items": ["index", "getting-started"] }
  ]
}

Content stays in src/content/docs; only the public route changes. The index page now renders at /docs/.

Where to go next

• Project structure explains which files belong to content, configuration, and overrides.
• Write content covers frontmatter, Markdown, code blocks, images, and page templates.
• Configure navigation covers nested groups and autogenerated directories.
• Use MDX components documents every shared content component with a rendered example and props table.