# Installation

Start a Dahlia documentation site from the starter template or add Dahlia to an existing Astro project.

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

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.

```sh
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](https://github.com/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.

<Steps>

1. **Install Dahlia.**

   Add the theme package to your Astro project.

   ```sh
   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.

   ```sh
   pnpm add @prosefly/astro-components
   ```

2. **Register the integration.**

   Configure Astro with the Dahlia integration.

   ```ts title="astro.config.ts"
   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.

   ```json title="theme.config.json"
   {
     "$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.

   ```ts title="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 };
   ```

5. **Add the first docs page.**

   Dahlia reads from `src/content/docs` by default.

   ```mdx title="src/content/docs/index.mdx"
   ---
   title: Overview
   description: Start here.
   ---

   Welcome to the docs.
   ```

6. **Start development.**

   ```sh
   pnpm dev
   ```

</Steps>

## Next Steps

- Review [Project Configuration](/docs/configuration/project/) to define the
  site identity, navigation, docs navigation, footer, and source repository.
- Review [Content Routing](/docs/configuration/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.