# 概览

了解 Lotus 提供了什么，以及文档主题如何组织内容。

import { Card, CardGrid, Steps } from '@prosefly/astro-components';

Lotus 是一个面向 Astro v7、Tailwind CSS v4 和 MDX 的可安装文档主题。
它提供页面外壳、文档路由、导航模型、主题 tokens，以及常用 MDX 组件，
让项目不需要从零搭建文档站点的基础结构。

## Lotus 包含什么

<CardGrid>
  <Card icon="lucide:layout-template" title="文档外壳" href="/docs/zh-cn/configuration/project/">
    通过主题配置渲染响应式 header、docs subnav、sidebar、文章布局、页面目录、
    页面元信息和 footer。
  </Card>
  <Card icon="lucide:route" title="路由" href="/docs/zh-cn/configuration/content-routing/">
    从 Astro content collection 生成文档页面、Markdown 源码路由、搜索索引、
    本地化 URL，以及带前缀的 docs 路由。
  </Card>
  <Card icon="lucide:search" title="搜索" href="/docs/zh-cn/configuration/search/">
    使用内置客户端搜索弹窗和生成的 JSON 索引，或通过组件覆盖替换搜索 UI。
  </Card>
  <Card icon="lucide:palette" title="设计 tokens" href="/docs/zh-cn/configuration/appearance/">
    配置 accent、gray、radius、color mode、字体，以及更底层的 CSS tokens。
  </Card>
  <Card icon="lucide:blocks" title="MDX 组件" href="/docs/zh-cn/components/callout/">
    使用 callout、cards、steps、tabs、accordion、file tree、badge 和 Iconify
    图标组合文档内容。
  </Card>
  <Card icon="lucide:replace" title="组件覆盖" href="/docs/zh-cn/customization/overriding-components/">
    当配置不够用时，替换 search、navbar、page header、page actions、
    contributors 和 previous/next navigation 等外壳组件。
  </Card>
</CardGrid>

## 文档树如何工作

Lotus 从 `docs` content collection 读取 MDX entry，然后在 `docsBase` 下
注入页面路由、Markdown 源码路由和搜索路由。默认 `docsBase: '/'` 时，Lotus 会生成：

- `/` 和嵌套文档页面
- `/*.md` Markdown 源码路由
- `/search.json` 搜索索引数据

`sidebars` 配置决定每个页面属于哪个 sidebar 和 subnav section。Locale 目录、
route prefix 和 fallback 行为见 [国际化](/docs/zh-cn/configuration/i18n/)。Loader base、
docsBase 和 slug 行为见 [内容路由](/docs/zh-cn/configuration/content-routing/)。

## 第一步

<Steps>

1. **安装主题。**

   安装 Lotus，并在 `astro.config.ts` 中注册 integration。当你自己的内容直接 import
   shared MDX components 时，再直接安装 `@prosefly/astro-components`。

   [安装 Lotus](/docs/zh-cn/installation/)

2. **配置路由和 locale。**

   决定文档挂载在哪里，以及本地化内容目录如何映射到公开 URL。

   [查看内容路由](/docs/zh-cn/configuration/content-routing/)

3. **搭建文档外壳。**

   设置项目身份、外观、navbar、sidebars、footer、page actions 和搜索行为。

   [配置项目](/docs/zh-cn/configuration/project/)

4. **编写内容。**

   添加 frontmatter、Markdown、图片、代码块和 shared MDX components。

   [查看内容编写基础](/docs/zh-cn/essentials/frontmatter/)

5. **在配置不够用时自定义。**

   使用 CSS tokens 调整视觉，使用组件覆盖替换外壳 markup 或行为。

   [自定义 Lotus](/docs/zh-cn/customization/css-styling/)

</Steps>