Widget 是 Markdown 里的组件：一个特殊代码块，语言写成 widget:名字，正文是 JSON。这篇是现成组件的用法，不是怎么自己写（那份见 写一个自己的 Widget）。
写错名字或 JSON 通不过校验时，这一块会变成普通代码块，整页其它部分照常。
写法
```widget:Alert
{
"message": "标题",
"type": "warning"
}
```
规则：
- 语言标识必须是
widget:加上组件名，大小写敏感。tabs不行，要用Tabs。 - 正文必须是一份 JSON 对象，字段就是这个组件的入参。
- 嵌套 Markdown 写在字符串里：换行用
\n，双引号用\"。 - 裸名按 personal → official 解析，你自己发布的同名组件会盖过官方的。要钉死官方实现，写成
widget:official/Alert。
这台实例上现有哪些组件、各自的字段 schema，看 /api/syntax 与 /api/widgets（都是匿名可读的实时清单）。
下面每个组件都先给出渲染结果，再给一份能直接抄的源码。
Alert：提示条
四种类型：success / info / warning / error。description 支持 Markdown。
```widget:Alert
{
"message": "标题",
"description": "辅助说明，支持 **Markdown**。",
"type": "info",
"showIcon": true,
"closable": false
}
```
| 字段 | 必填 | 说明 |
|---|---|---|
message | 是 | 标题 |
description | 否 | 辅助说明，支持 Markdown |
type | 否 | success / info / warning / error，默认 info |
showIcon | 否 | 默认 true |
closable | 否 | 默认 false；关闭只存在这次页面加载 |
HighlightBlock：结论块
面积比 Alert 大，适合放结论。颜色跟主题走，不要在 style 里写死颜色值。
```widget:HighlightBlock
{
"content": "### 标题\n\n完整 Markdown 都可以放在 `content` 里。"
}
```
| 字段 | 必填 | 说明 |
|---|---|---|
content | 是 | Markdown |
style | 否 | 排版（padding、圆角）。颜色跟主题，写 hex 会被忽略 |
Table：数据表
列定义和数据分开，比 GFM 表格好生成。单元格三种写法：字符串按行内 Markdown 渲染（可以放 `code`、粗体、链接）；数字直接写数字，整列都是数字时自动右对齐；布尔值画勾 / 横线。表格拉满正文宽度，超出时横向滚动。
```widget:Table
{
"caption": "本周销量",
"sortable": true,
"columns": [
{ "title": "商品", "dataIndex": "name" },
{ "title": "销量", "dataIndex": "sales" },
{ "title": "在售", "dataIndex": "active" }
],
"dataSource": [
{ "name": "`T-Shirt`", "sales": 1204, "active": true }
]
}
```
| 字段 | 必填 | 说明 |
|---|---|---|
columns | 是 | title、dataIndex，可选 align：left / center / right（不写时数字列右对齐） |
dataSource | 是 | 行对象数组，取值字段对应 dataIndex；值可以是字符串（行内 Markdown）、数字、布尔 |
sortable | 否 | 点表头排序，默认 false |
caption | 否 | 表标题 |
Tabs：选项卡
content 是 Markdown，可以在 JSON 字符串里嵌代码块（三个反引号写在字符串中间，不要单独占一行，否则会截断外层 fence）。
| 字段 | 必填 | 说明 |
|---|---|---|
tabs | 是 | 每项要有 key、label、content |
defaultActiveKey | 否 | 默认打开哪一项 |
Collapse：折叠
accordion: true 时同时只展开一项。
| 字段 | 必填 | 说明 |
|---|---|---|
items | 是 | key、label、content；defaultOpen 默认 false |
accordion | 否 | 默认 false |
TodoList：可勾选清单
勾选写在这台浏览器的 localStorage 里。换文档或换场景时换一个 persistKey，避免状态串台。id 是稳定主键，改文案不要改 id。
| 字段 | 必填 | 说明 |
|---|---|---|
items | 是 | 每项要有字符串 id、title；content / checked / disabled 可选 |
persistKey | 否 | 不设则各文档可能抢同一份本地状态 |
sortCompletedLast | 否 | 已勾选项排到后面，默认 false |
showProgress | 否 | 顶部「已完成 n / N」，默认 true |
Stat：指标卡
报告开头的几个核心数字。value 是数字就自动加千分位，带单位写成字符串。delta 带符号，箭头方向按符号推；下降是好事（错误率、耗时）时写 "tone": "positive"。
| 字段 | 必填 | 说明 |
|---|---|---|
items[].label / value | 是 | 指标名与主数字 |
items[].delta | 否 | 变化量，带符号 |
items[].trend | 否 | up / down / flat，不写按符号推 |
items[].tone | 否 | positive / negative / neutral，不写时涨为好、跌为坏 |
items[].hint | 否 | 小字说明 |
Steps：步骤与时间线
带状态的步骤。给 current（0 起）就自动把之前的标为完成、之后的标为未开始；也可以每步自己写 status。meta 放时间，就是一条时间线。
| 字段 | 必填 | 说明 |
|---|---|---|
items[].title | 是 | 步骤标题 |
items[].description | 否 | 说明，支持 Markdown |
items[].meta | 否 | 时间 / 耗时小字 |
items[].status | 否 | done / current / pending / error |
current | 否 | 进行到第几步（0 起） |
direction | 否 | vertical（默认）/ horizontal |
LinkCards：链接卡片
「相关资源」「延伸阅读」用它。整卡可点，跨站链接新标签打开；href 只接受 http(s)、站内路径、锚点和 mailto。
| 字段 | 必填 | 说明 |
|---|---|---|
items[].title / href | 是 | 标题与地址 |
items[].description | 否 | 摘要，最多两行 |
items[].badge / meta | 否 | 中性徽章与小字 |
Mindmap：脑图
把一个话题拆成树。节点是真实文字，页内搜索能命中、读屏能念出；有子节点的会带折叠箭头，你展开过的节点不会被后续更新收起。
| 字段 | 必填 | 说明 |
|---|---|---|
root.title | 是 | 节点文字，尽量短 |
root.note | 否 | 标题后的小字注解 |
root.href | 否 | 节点链接 |
root.children | 否 | 子节点，结构相同，最深 8 层 |
collapseDepth | 否 | 默认展开到第几层（根算第 1 层），不给就全展开 |
想要放射状的手绘感脑图，用 ```mermaid 的 mindmap——代价是整张图变成一幅画，文字搜不到也读不出来。
Gantt：甘特图
排期表。任务按日期落到时间轴上，带负责人、进度和今日线。刻度粒度自动跟着跨度走：两周内按天、十周内按周、更长按月。
| 字段 | 必填 | 说明 |
|---|---|---|
tasks[].title / start | 是 | 任务名与开始日期（YYYY-MM-DD） |
tasks[].end / days | 否 | 结束日期（含当天）或持续天数，end 优先；都不给按单日里程碑 |
tasks[].section | 否 | 分组名，相邻同名算一组 |
tasks[].owner | 否 | 负责人，显示在任务名下方 |
tasks[].status | 否 | planned（默认）/ active / done / risk |
tasks[].progress | 否 | 完成度，0.45 和 45 都认 |
tasks[].milestone | 否 | 画成菱形节点 |
today | 否 | 今日线画在哪天，不给按读者当天 |
showToday | 否 | 默认 true |
日期按 UTC 折算，不同时区的读者看到的位置一致。想让截图长期稳定就把 today 写死。
RawHtml / Iframe：沙箱 HTML
同一实现、两个注册名。内容放进 iframe 的 srcdoc，默认允许脚本，不允许 allow-same-origin 和顶层跳转。不继承宿主页样式，必须给 height。
sandbox 白名单：allow-scripts、allow-forms、allow-modals、allow-popups、allow-downloads 等。传了数组就按过滤后的结果用（空数组 = 最严）；只有完全不写 sandbox 才回落到默认的 allow-scripts。
| 字段 | 必填 | 说明 |
|---|---|---|
html | 是 | iframe srcdoc |
height | 是 | 数字按 px |
width | 否 | 默认 100% |
sandbox | 否 | token 数组 |
title | 否 | 无障碍标题 |
Diff、Mermaid 和 Chart
Diff 与 Mermaid 更常见的写法是语言标识，而不是 widget:；数据图表用 widget:Chart，三种都在 画流程图和差异对比 里展开：
```mermaid
flowchart LR
A["写 md"] --> B["jdu push"]
```
```diff
- 旧
+ 新
```
完整例子在 画流程图和差异对比。也可以直接走 Widget：
官方组件一览
本站当前注册的官方组件：
jdu widget list 能看到本站实际注册了哪些、是否 active。下线的名字按未注册处理，fence 降级成代码块。