排版

本页集中展示 Lotus 支持的 Markdown 模式，便于在同一个页面中检查排版变更， 无需在不同的功能页面之间来回切换。页面有意以普通内容元素为主，而不是使用 自定义布局组件。

Lotus 的正文排版针对带有侧边栏和页内目录的文档页面进行了优化。正文在密集的 导航旁仍应保持易读，标题则需要清楚地区分章节，同时避免呈现为页面级展示文字。

Lotus 使用官方 Tailwind CSS Typography 插件作为 Markdown 的排版基础。为渲染后的 内容添加 class="prose"；如果外层布局已经限制了内容宽度，再添加 max-w-none。 可以使用 prose-sm、prose-base 或 prose-lg 选择不同的字号层级。

对于不应继承文章排版的嵌入式应用或组件区域，请使用 not-prose。排除规则由 Tailwind Typography 负责处理，因此嵌套控件和组件标记不会受到正文样式级联的影响。

标题

上方的页面标题由 frontmatter 渲染为文档的 h1。正文标题从 h2 开始，以保持 页内目录和文档大纲稳定。

三级标题

子章节的标题应小于章节标题，但在较长的技术文档中仍需要足够醒目。它适合用于 聚焦的主题、配置分组，或较大章节中的操作步骤。

四级标题

较小的标题适合内容密集的参考文档，尤其适合放在短段落或列表之前。

五级标题

五级标题应保持紧凑，不应打断正文的阅读节奏。

六级标题

只有少数层级很深的参考页面会用到六级标题。

段落与换行

段落之间使用空行分隔。段落间距应清晰到足以快速浏览，同时保持紧凑，让中等长度的 指南仍能形成连续的阅读体验。

这个段落在第一句话后使用硬换行。
第二行在视觉上应与第一行保持关联。

强调

当术语需要突出显示时，请使用粗体文字。斜体文字适合少量用于措辞、引文或 引用标签。内容确实需要更强的强调时，可以组合为粗斜体文字。

GitHub Flavored Markdown 还支持使用删除线文字表示已删除或过时的内容。

链接

安装指南之类的行内链接应保持清晰可见，同时避免从句子中 夺走过多注意力。

同一个 URL 多次出现时，引用式链接会很方便。这个句子链接到 Astro 文档。

脚注

脚注适合补充不应打断正文阅读的小段说明。¹

行内代码

docsBase、themeConfig.docsNav、theme.config.json 和 --lotus-text-muted 等行内代码应自然地嵌入正文，不应改变段落的阅读节奏。

列表

无序列表适合展示相关说明或功能：

• 配置项目元数据、favicon、页脚链接和外观 token。
• 使用 MDX 和默认文档布局编写页面。
• 在项目需要自定义行为时覆盖指定的主题组件。

有序列表适合展示操作流程：

1. 安装主题包和 Astro integration。
2. 在配置的 docs collection 中添加文档内容。
3. 启动开发服务器并检查生成的导航。

嵌套列表应保持紧凑：

• 外观
  • 强调色
  • 灰阶
  • 圆角
• 导航
  • 顶部导航链接
  • 侧边栏分组
  • 页脚分区

GitHub Flavored Markdown 支持任务列表：

• 创建文档结构
• 配置 MDX 和 Expressive Code
• 发布软件包

引用块

文档排版应清楚地呈现内容结构，而不必把每个章节都变成视觉组件。

引用块可以包含多个段落。

第一段用于引出引用的观点。

第二段应保持相同的 muted 色调和左侧边线。

代码块

围栏代码块默认使用 Expressive Code 渲染。

import { defineConfig } from 'astro/config';
import lotus from '@prosefly/astro-theme-lotus';

export default defineConfig({
  integrations: [lotus()],
});

同时也支持纯文本代码块。

src/content/docs/
  overview.mdx
  configuration/
    appearance.mdx

包管理器命令

包含包管理器安装命令的 shell 代码块，可以由 Lotus Markdown integration 转换为 包管理器标签页。

pnpm add @prosefly/astro-theme-lotus

同时也支持 Python 包管理器命令。

pip install astro-lotus-example

uv add astro-lotus-example

poetry add astro-lotus-example

pdm add astro-lotus-example

图片

图片应保持自身宽高比、适应内容栏宽度，并继承正文区域的圆角。

图片说明应使用 muted 文本和紧凑间距。

表格

表格适合展示紧凑的参考信息。

较长的表格在窄屏设备上也应保持易读。

水平分隔线

分隔线上方的内容应与当前页面保持关联，下方内容则应呈现为独立的收尾区块。

最后的段落可用于检查正文、分隔线和后续内容之间的视觉关系。

转义字符

经过转义的 Markdown 标点应按字面显示：

*这段文字不应显示为斜体。*

`这段文字不应显示为行内代码。`

原始 HTML 与 MDX

MDX 允许在 Markdown 内容中使用 HTML 元素。Ctrl + K 等键盘标签应与周围文字对齐。

高亮文字、API 和 小号文字等行内 HTML 应继承周围正文的排版节奏。

新增内容可以使用 带下划线的文字，已删除的内容可以使用 删除内容。

数学和技术记号可以使用行内下标与上标：H₂O 和 x²。

程序输出可以使用 200 OK，变量可以使用 request， 短引用可以使用 语义化 token 让组件保持稳定，引文出处则可以使用 Lotus 设计说明。