安装

新建文档站点时，推荐从 Dahlia starter template 开始。已有 Astro 项目时，可以手动安装 Dahlia。

使用 Starter 模板

如果你想最快得到一个可运行站点，使用 starter。

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

模板源码在 prosefly/astro-template-dahlia-starter。

站点跑起来后，替换示例内容，并在 Dahlia theme config 中更新项目名称、导航、 sidebar 结构、外观、footer 和源码仓库。

手动设置

当项目已经存在，或你想逐步接入 Dahlia 时，使用手动设置。

1. 安装 Dahlia。

   将主题包加到 Astro 项目。

   pnpm add @prosefly/astro-theme-dahlia

   当你自己的 MDX 或 Astro 文件直接 import cards、steps、tabs、callouts、 badges、file trees 等 shared components 时，再直接安装 @prosefly/astro-components。

   pnpm add @prosefly/astro-components

2. 注册 integration。

   在 Astro 配置中接入 Dahlia integration。

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

3. 创建 theme config。

   先配置项目身份和最小 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"]
       }
     ]
   }

   如果 Astro 项目已经有站点首页，并且文档应该放在 /docs/ 下，设置 docsBase: '/docs'。

   当你需要 TypeScript、imports 或动态值时，可以直接在 astro.config.ts 里传入 dahlia({...})。这些选项会覆盖 theme.config.json 中的值。

4. 注册 docs collection。

   创建 src/content.config.ts，并使用 Dahlia 提供的 loader 和 schema。

   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. 添加第一篇文档。

   Dahlia 默认从 src/content/docs 读取文档。

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

6. 启动开发服务器。

   pnpm dev

下一步

• 查看 项目配置，设置站点身份、导航、docs navigation、footer 和源码仓库。
• 在移动文档路径或修改 docs loader base 前，先阅读 内容路由。
• 发布前运行 pnpm check，验证 content collections、MDX imports、Astro 组件和 TypeScript。