入门
概览
了解 Dahlia 提供了什么，以及文档主题如何组织内容。
Dahlia 是一个面向 Astro v7、Tailwind CSS v4 和 MDX 的可安装文档主题。 它提供页面外壳、文档路由、导航模型、主题 tokens，以及常用 MDX 组件， 让项目不需要从零搭建文档站点的基础结构。
Dahlia 包含什么
文档外壳
通过主题配置渲染全高左侧导航栏、带目录的右侧文章布局、移动端文档菜单、 页面元信息和 footer。
路由
从 Astro content collection 生成文档页面、Markdown 源码路由、搜索索引、 本地化 URL，以及带前缀的 docs 路由。
搜索
使用内置客户端搜索弹窗和生成的 JSON 索引，或通过组件覆盖替换搜索 UI。
设计 tokens
配置 accent、gray、radius、color mode、字体，以及更底层的 CSS tokens。
MDX 组件
使用 callout、card、steps、tabs、accordion、file tree、badge、media、embed 和 Iconify icon 组织页面。
组件覆盖
当配置不够用时，替换 search、navbar、page header、page actions、 contributors 和 previous/next navigation 等外壳组件。
Dahlia 站点的四个部分
astro.config.ts注册 Dahlia integration。src/content.config.ts使用 Dahlia loader 和 schema 定义docscollection。theme.config.json配置项目身份、路由、导航、搜索、源码链接、外观和组件覆盖。src/content/docs/**/*.mdx保存文档页面。
Dahlia 读取 collection，并在 docsBase 下注入页面、Markdown 源码和搜索路由。
默认 docsBase: '/' 时会生成：
/和嵌套文档页面/*.mdMarkdown 源码路由/search.json搜索索引数据
docsNav 配置决定每个页面属于哪个 sidebar 和 subnav section。Locale 目录、
route prefix 和 fallback 行为见 国际化。Loader base、
docsBase 和 slug 行为见 内容路由。
第一步
-
安装主题。
安装 Dahlia，并在
astro.config.ts中注册 integration。当你自己的内容直接 import shared MDX components 时，再直接安装@prosefly/astro-components。 -
配置路由和 locale。
决定文档挂载在哪里，以及本地化内容目录如何映射到公开 URL。
-
搭建文档外壳。
设置项目身份、外观、siteNav、docsNav、footer、page actions 和搜索行为。
-
编写内容。
添加 frontmatter、Markdown、图片、代码块和 shared MDX components。
-
在配置不够用时自定义。
使用 CSS tokens 调整视觉，使用组件覆盖替换外壳 markup 或行为。
最后更新于 2026年10月14日
