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