blocks

区块

比 Markdown 更丰富的内容都要作为以下区块之一放入页面。区块列表由框架定义，项目无法添加新区块。如果你需要的内容不在列表中，就必须使用图示或正文。发明新的 className 并不是解决办法；请参阅 Styling。

提示框

:::note、:::tip、:::info、:::warning（:::warn、:::caution）、:::danger 和我们自有的 :::source。纯 Markdown，无需导入：

:::warning[Required]

Careful, and *emphatic*.

:::

方括号中的标签是可选的；如果不填写，提示框会显示自身名称。:::source 是带书签图标的灰色提示框，用于标注文本中某个观点的出处：书名、作者、年份。页面内编辑器也会绘制相同的提示框，因此编写时看到的效果与最终效果一致。

<VideoEmbed url="..." />

以 16:9 嵌入的 YouTube 视频。全局注册，无需导入，也不必做其他设置：

<VideoEmbed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />

<LinkEmbed url="..." />

将链接呈现为卡片：页面标题、一行简介、网站名称和图标，以及右侧的预览图。也是全局注册。段落的重点是某个链接、工具、代码库或值得打开的参考资料时，请使用它；句子中的链接仍使用 Markdown 链接。

只有 url 是必填项。其他属性取自页面自身的 og:title、og:description、og:site_name、og:image 和图标；有人把链接粘贴到空行时，工作室会读取这些信息。手动编写时，请从页面自身的标签中复制这些属性，不要凭空编造；无法读取的属性就省略：如果卡片只有 url，它会将地址显示为标题、将主机名显示为网站名称。切勿将 image 指向尚未确认能加载的图片。

<LinkEmbed
  url="https://fumadocs.dev/"
  title="Fumadocs"
  description="The React.js documentation framework."
  site="Fumadocs"
  image="https://www.fumadocs.dev/banner.png"
  favicon="https://www.fumadocs.dev/icon.png"
/>

<FileAttachment ... />

提交到页面并以下载卡片形式提供的文件。也是全局注册。只有 href 是必填项；size 是字节数，uploadedAt 的格式为 YYYY-MM-DD，note 最多 200 个字符。

<FileAttachment
  href="/files/docs/9f2c1a8b.zip"
  name="latency-harness.zip"
  size="248193"
  uploadedAt="2026-08-22"
  note="The harness behind the Q3 p99 numbers. Run make bench."
/>

<DocCardList />

每个章节落地页末尾都会显示的子页面网格。无需导入：页面会将其绑定到树中的自身位置。它会自动生成标题——网站根目录中显示 “Sections”，章节内显示 “In this section”——因此不要在它上方添加 ##。要使用其他标题，请传入 title="…"。当前页面不会列入其中，每张卡片都会显示目标页面的 description，因此每个页面都需要在 front matter 中填写该字段，每个章节也都需要在 meta.json 中填写该字段。

表格

仅使用 GFM Markdown 表格。table 元素位于可水平滚动的容器中，正文排版会处理表头、分隔线和单元格内边距，因此宽表格会滚动，而不是撑宽页面。分隔行中的冒号用于设置列的对齐方式（:---: 居中，---: 右对齐，适合数字列）；单元格支持行内 Markdown，因此链接、code 和 粗体 都可以使用。

如果单元格大多是用于比较而非查阅的数字，请改用图表。

图片

以文件形式提供的截图或示意图就是普通 Markdown。边框、标题栏和说明文字由主题提供，因此无需输入包装器：

![The blocks of a page, with one being written in](/img/docs/editor.png "A grip in the left margin moves a block; the bar at the foot commits the page.")

• 第一个方括号中是 alt：让看不到图片的人了解图片内容。写一句描述内容的话，不要写“X 的截图”。
• 如果图片没有传达正文中尚未说明的信息，它就是装饰性图片。写成 ![](…)，系统会将其标记为装饰性图片，并让屏幕阅读器跳过。
• 路径后引号中的字符串是可选的，会成为说明文字。
• 图片按自身尺寸显示，但宽度不超过文本宽度；在宽屏上会稍宽一些，高度则永远不会超过 --jd-shot-height，因此大型导出图片不会占满整个窗口。点击图片会在变暗的背景上打开原始文件；将指针移到图片上会显示工具栏，可用于放大、复制或下载原始文件。导出截图时应使用适合阅读的尺寸；较小的图片不会被拉伸以填满栏宽。
• 文件存放在项目的 docs/_uploads/img/docs/ 中，页面内编辑器会将上传的文件放在此处。
• SVG 会根据单个文件中的颜色模式切换：在深色模式下，页面会以 #dark 再次绘制它，因此在 svg:target 下设置的调色板就是深色模式使用的调色板。只有一种调色板的 SVG 在两种模式下看起来都一样。
• 没有路径的图片，例如 ![团队徽标]()，会显示一个占位图，并注明无法下载。从其他网站粘贴的页面中，每张浏览器未获准获取的图片都会显示这样的占位图。请用实际文件替换它，绝不要链接到其他网站。路径对应的资源没有图片时，也会显示相同的占位图，并注明无法加载。

宽度

表格或图片可以比文章栏更宽。将其单独放在 :::wide 或 :::full 中，使用普通 Markdown，无需导入：

:::wide

| Product | Purpose | Business capabilities | Key systems |
| --- | --- | --- | --- |
| Field service | Customers, assets and service delivery in one platform | Case management, work orders | A CRM |

:::

• 不加包装器时，内容宽度就是栏宽，这适用于几乎所有情况。:::wide 会稍宽一些，适合列宽狭窄的表格或需要看清细节的截图。:::full 会延伸到页面边缘，适用于作为页面核心内容的总览图。
• 两种模式下，内容都在栏内居中，且不会比栏宽窄，因此在小屏幕上看起来就是普通内容块。
• 加宽后的图片会填满所在内容块，并取消截图高度上限，因此只有导出尺寸足以填满内容块的图片才适合加宽。
• 只有表格或单独一张图片可以加宽，而且只能作为页面本身的内容块加宽。用于其他内容周围，或放在提示框、标签页等其他内容块中时，包装器会被忽略，内容仍按栏宽显示。
• 在页面内编辑器中，内容块的拖动手柄菜单提供“宽度”选项；可加宽内容块侧边的拖动手柄，可在三种宽度间拖动切换。

```mermaid 代码围栏

以代码形式编写、由浏览器中的 Mermaid 渲染的序列图、流程图或状态图。使用普通 Markdown，无需导入。图表内嵌时会像图片一样缩小到页面栏宽；点击后会在全屏视图中打开，可用触控板平移，也可通过捏合手势缩放。较长的流程图应按自然章节拆分成多个代码围栏，并与正文交错排列，而不是绘制成一张很高的图。

在页面内编辑器中，代码围栏代表图表本身，而不是其源代码：点击节点即可重命名或更改形状，从一个节点拖到另一个节点即可绘制连线。每次编辑都会以 Mermaid 源代码的形式写回代码围栏。/diagram 会插入一个流程图模板；空代码围栏则会提供流程图、序列图或状态图供你选择，以此开始绘制。

代码围栏

Shiki 会为每个代码围栏添加语法高亮，语言标识后的元字符串也是代码块的一部分：

```ts title="lib/cart.ts" lineNumbers
```

title="…" 会显示文件名标题，lineNumbers 会为行编号，注释标注会在原位标记行：用于差异对比的 // [!code highlight]、// [!code ++] 和 // [!code --]，用于淡化其余内容的 // [!code focus]，以及用于突出显示词元的 // [!code word:parseDocument]。两个相邻的代码围栏都带有 tab="Server" 时，会合并为一个标签页代码块，无需注册。页内编辑器会保留元字符串的原样，并原封不动地打印出来，因此带标题的代码围栏会在标题栏中显示文件名，保存时也会保留相同的标题和标签页。在编辑器中编写的代码围栏会在输入时使用与构建后页面相同的 Shiki 和主题添加语法高亮；鼠标指向代码围栏时，框架角落的下拉菜单会显示语言名称。

jd-fig 图示

由图示技能绘制的内嵌 SVG 或 HTML 图示。点击图形会在与 Mermaid 图表相同的全屏画布中打开，并支持平移、缩放和缩略图；无需对图示进行任何额外设置。作为备用方案的 HTML 图示没有可放到画布上的图形，因此会保留在原处。图示技能提供了一张路由表，将段落主题对应到能展示该主题的图示形式；references/forms/ 下为每种形式提供布局参考，还提供所有箭头都必须遵循的连接规则，以及一份索引，列出 Claude Code 内置技能中适用于各类图示的技能（机制图使用 artifact-diagramming，图表使用 dataviz）。你也可以使用其他任何可用的视觉技能。

<Chart />

使用 shadcn 的图表组件在 Recharts 上绘制的条形图、折线图、面积图、饼图或雷达图，展示字面数据，采用品牌色 --chart-1 至 --chart-5，并带有工具提示和图例。x 指定用于标记每一行的字段，series 按颜色顺序将每个绘图字段映射到对应标签；stacked、horizontal、unit 和 caption 为可选项。图表技能会说明哪种类型适合回答哪类问题。在页内编辑器中，它是一个可以移动和删除的块，但需要在源代码中编辑。

<Chart type="bar" x="month" data={[{ month: "Apr", saves: 186 }, { month: "May", saves: 305 }]} series={{ saves: "Studio saves" }} />

布局组件

框架会注册五类布局组件，因此页面无需导入即可使用。其他任何标签都不会渲染。

• <Tabs items={['npm','bun']}><Tab value="npm">…</Tab></Tabs>。一条说明，适用于多个环境，无需编写三个几乎相同的章节。
• <Steps><Step>…</Step></Steps>。左侧带有竖线的编号步骤流程。比 1. 2. 3. 更合适，尤其是每个步骤都包含代码块时。
• <Files><Folder name="docs"><File name="index.mdx" /></Folder></Files>。目录树；否则就只能在代码围栏里用 ASCII 字符画出来。
• <Cards><Card title="ADR 0015" href="/decision-records/0015-hosted-studio-and-static-publishing" /></Cards>。精选链接集合；<DocCardList /> 会列出所有子项。
• <Accordions><Accordion title="…">…</Accordion></Accordions>。折叠收起大多数读者会跳过的答案。type="multiple" 允许同时展开多个面板，defaultValue 是默认展开面板的标题，而在面板上添加 id 会提供复制链接按钮，以及一个可展开该面板的锚点。

其他一些文档框架提供的组件在这里会被刻意省略：

组件	原因
Callout	:::note 等标记在 Markdown 中也能实现相同效果，而且页内编辑器会绘制它们。
ImageZoom	Markdown 中的  会渲染为 DocImage，它本身就会加边框、限制尺寸并支持缩放。
CodeBlockTabs	Markdown 中相邻的两个代码围栏加上 tab="…" 就能实现相同效果。
DynamicCodeBlock	用于高亮运行时生成的代码，而不是文件中的代码。这里的代码围栏全都来自文件。
Banner、GitHubInfo	它们属于网站界面，而不是页面内容。
InlineTOC	需要一个 TOCItemType[] 数组，没人能手动编写。页面都会显示侧边栏目录。
TypeTable、AutoTypeTable	Markdown 表格中添加一列填写类型，另一列说明是否必填，就能表达相同内容。
GraphView	这个规模的网站通过侧边栏导航即可。

样式

网站的排版由框架自行处理：标题字号、行长、区块间距，以及表格和代码框的样式。页面不会重新设置这些样式。docs/ 下的文章正文一律使用纯 Markdown。

项目的视觉风格只在一处设置，而不在页面中设置：.jotdown/config.json 中的 theme。每种模式下的 Shadcn 令牌名称 background、foreground、primary、destructive 和 chart-1 到 chart-5，会为每个区块、图示和图表着色，因此两种色彩模式都能自动生效，无需页面知晓。sections 通过指定令牌为各个章节设置颜色，radius 用于圆角，fonts 用于指定 sans、serif 和 mono 字体。

文档中的 className

如果某段内容需要强调，Markdown 已经提供了相应方式：引用块（>）、粗体、提示框（:::note、:::warning、:::source，用于引用）。

docs/ 中只允许使用一个 className，除此之外一概不允许：jd-fig，用于由图示技能绘制的内联 SVG 或 HTML 图示。这是图片，不是正文。

其他任何内容都无法由人类编写、无法在页内编辑器中显示，还会在仓库中留下永久污点。不要为正文编造 className，也不要在文档中使用 Tailwind 工具类：只有框架自身组件使用的类才会被编译，因此其他类都会渲染为无样式的元素。

经验法则

• 不要在页面中硬编码颜色或字体。图形使用 --jd-fig-* 令牌绘制，图表使用品牌的图表颜色；唯一的例外是编辑类插图，即拥有自定义配色的 SVG 文件。
• 不要重新设置文章的样式。如果标题、段落或表格看起来不对，就不要改动，并告知框架维护者。
• 除非用户要求使用 Mermaid，否则图表应是使用 figure 技能绘制的内嵌 SVG/HTML 图形。Mermaid 适用于复杂、技术性强且确定性的参考图表；其他情况都应使用旨在降低认知负担的说明性图形。

以下是表格形式的相同规则，针对大家实际会遇到的情况：

想要实现	不要这样做	应该这样做
突出显示一段内容	在文字外面套一个 <div className="…">	使用 > 块引用、粗体，或 :::note / :::warning 提示框
为段落添加颜色或边框	新建一个类，或在文档中使用 Tailwind 工具类	使用普通 Markdown；如果内容是图片，则使用 jd-fig 图形
为项目指定颜色	在页面中使用十六进制值	在 .jotdown/config.json 的 theme 中使用 shadcn 令牌
为项目指定字体	在页面中使用 <style>	在主题的 fonts 中指定字体
在官方参考文档中绘制流程图或状态图	手绘图形	使用 ```mermaid 围栏代码块
在文字旁边添加插图	使用 ```mermaid 围栏代码块	使用 figure 技能绘制 jd-fig 图形
添加一张以杂志风格开篇的故事图片	将图表的方框改名，或把 SVG 粘贴到页面中	使用 editorial-illustration 技能生成 SVG 文件，并在 :::wide 中以 Markdown 图片形式展示
展示数字、趋势或对比	使用方框和箭头，或用一段话罗列数据	按照 chart 技能的说明使用 <Chart /> 块