怎么写一篇文档

简牍吃的是普通 Markdown。先按 GitHub 上那种 md 写，再按需加 Widget 和图表。

正文第一段（标题、代码块、列表都不算）会截成列表页上的摘要，所以开篇写一句人话。

标准语法

CommonMark 都能用：标题、段落、粗体、斜体、行内代码、引用、有序/无序列表、链接、图片、分隔线。标题会生成锚点；同一篇里标题重名时自动加后缀。

# 一级标题

段落里可以有 **粗体**、*斜体*、~~删除线~~ 和 `代码`。

> 引用里还可以再写列表。

- 无序
1. 有序

[链接文字](https://docs.mszhou.com)
![说明](./img/local-image.svg)

GFM 扩展

简单静态表用 GFM 表格。要固定列对齐、给脚本生成时，用 Table Widget，见 在文档里用 Widget。

任务列表示例：

• 标题和第一段
• 一张本地图片
• 需要时再加 Widget

脚注在预渲染时就已经展开。¹

代码块

三个反引号，语言标识决定高亮或特殊渲染：

```ts
export function hello(name: string) {
  return `hi, ${name}`;
}
```

vega-lite / vega / canvas 在协议里预留了，对应 Widget 还没上；现在会按普通代码块展示，不会报错。

本地图片和文件

相对路径会被收集并上传。下面这张图和这篇教程放在一起：

规则：

• Markdown 图片、HTML src / href、指向本地文件的链接都会收
• http(s):、data:、mailto:、站点绝对路径（以 / 开头）、纯锚点不收，原文保留
• 引用链最多 10 层；环会断开，不会死循环
• 文件不存在时跳过并在 stderr 打 warn:，push 本身不会因此失败
• 相同内容只传一次（按 sha256）

上传之后，入口文档里的相对路径被改写成 /blob/<hash>。打开这篇的 .md 原文就能看到改写结果：地址栏文档 URL 后面加 .md。

嵌套 Markdown

入口里链到另一份 md，这份 md 会作为资源上传，链接同样改写。例如：嵌套文档示例

注意两件事：

1. 被链到的 md 不是另一篇文档页面，只是可下载的原文。要单独成页，对那份文件再 jdu push 一次。
2. 嵌套 md 内部的相对图片目前不会再改写。需要图片的内容写在入口文档里，或把那份 md 作为独立文档发布。

原始 HTML

可以直接写常见标签，会经过白名单过滤：

script、iframe、object、事件属性（onclick）、javascript: 协议会被剥掉。要跑脚本或嵌第三方页面，用 RawHtml / Iframe Widget，不要裸写 <iframe>。

建议的文件布局

notes/
├── index.md          ← 对这一份执行 jdu push
├── img/
│   └── cover.png
└── assets/
    └── appendix.md   ← 被入口链接，当资源上传

jdu push notes/index.md --title "今天的笔记"

标题缺省取首个一级标题；没有 # 标题时用文件名。

教程目录：使用简牍 · 下一篇：发布、更新与版本