安装 Dahlia

新建文档站点时使用 starter template。已有 Astro 项目，或者希望了解每个 必需文件时，使用手动安装流程。

Starter template

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

模板维护在 prosefly/astro-template-dahlia-starter。 启动后，修改 theme.config.json，并替换 src/content/docs 下的示例内容。

手动安装

下面从一个 Astro 项目开始，最终会得到运行在 http://localhost:4321/ 的 Dahlia 文档站点。如果还没有 Astro 项目，先创建一个：

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

1. 安装 Dahlia。

   pnpm add @prosefly/astro-theme-dahlia

   Dahlia 已包含主题运行所需的 integrations。当自己的 MDX 文件要 import 共享组件，或要在 astro.config.ts 中自定义 Astro Components integration 时，再直接安装 @prosefly/astro-components。

   pnpm add @prosefly/astro-components

2. 注册 integration。

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

3. 注册 docs collection。

   创建 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. 添加最小主题配置。

   在项目根目录创建 theme.config.json：

   {
     "$schema": "https://prosefly.dev/schema/dahlia.json",
     "name": "Acme 文档",
     "description": "Acme 项目文档。",
     "docsNav": [
       {
         "label": "指南",
         "icon": "lucide:book-open",
         "items": ["index"]
       }
     ]
   }

5. 创建第一篇文档。

   ---
   title: 概览
   description: 了解如何使用 Acme。
   ---
   
   欢迎阅读 Acme 文档。

6. 启动开发服务器。

   pnpm dev

   打开 http://localhost:4321/。页面中应显示“概览”内容和“指南”侧边栏。

添加另一篇文档

创建 src/content/docs/getting-started.mdx：

---
title: 快速开始
sidebar:
  icon: "lucide:rocket"
---

在这里编写第一个任务。

然后把 content entry ID 加入 docsNav：

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

Content entry ID 是 src/content/docs 下的相对路径，不包含 .mdx 扩展名。 嵌套文件使用 configuration/authentication 这样的斜杠路径。

将文档放到 /docs

最小配置会把文档放在 /。如果产品首页和文档需要共存，设置 docsBase 并更新顶部导航：

{
  "name": "Acme",
  "docsBase": "/docs",
  "siteNav": [
    { "label": "首页", "href": "/" },
    { "label": "文档", "href": "/docs/" }
  ],
  "docsNav": [
    { "label": "指南", "items": ["index", "getting-started"] }
  ]
}

内容仍保存在 src/content/docs，只有公开 URL 改变。Index 页面会渲染到 /docs/。

下一步

• 项目结构 解释内容、配置和 overrides 分别应该放在哪里。
• 编写内容 介绍 frontmatter、Markdown、 代码块、图片和页面模板。
• 配置导航 介绍嵌套分组和目录自动生成。
• 使用 MDX 组件 提供每个共享内容组件的示例 和 props 表格。