概览
了解 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。
Dahlia 布局
使用 Dahlia 的左侧导航、居中文章列、sticky 目录、splash 页面和独立 text 页面。
组件覆盖
当配置不够用时，替换 search、navbar、page header、page actions、 contributors 和 previous/next navigation 等外壳组件。
文档树如何工作
Dahlia 从 docs content collection 读取 MDX entry，然后在 docsBase 下
注入页面路由、Markdown 源码路由和搜索路由。默认 docsBase: '/' 时，Dahlia 会生成：
/和嵌套文档页面/*.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年8月24日
