SYNTAX

文章语法

当前文章支持 Markdown、GFM、数学公式、Mermaid 和预留组件块;后续主题、问卷、 投票与交互动画都可以继续扩展。

当前语法

这些能力已经接入文章详情页和编辑器实时预览。

基础写作

这些语法会直接进入文章正文和编辑器预览,适合作为默认写作格式。

标题层级

已支持

支持 1-6 级标题,正文中建议从二级标题开始组织章节。

# 一级标题
## 二级标题
### 三级标题

文本格式

已支持

支持粗体、斜体、粗斜体、删除线、行内代码和高亮文本。

**粗体** *斜体* ***粗斜体*** ~~删除线~~ `code` ==高亮==

列表

已支持

支持无序、有序、嵌套列表和任务列表。

- [x] 已完成
- [ ] 待完成

1. 第一步
2. 第二步

结构内容

已支持

支持外链、图片、引用块、分隔线、表格和脚注。

[链接](https://example.com)

![图片](https://example.com/a.png)

[^1]: 脚注内容

图片尺寸

已支持

Markdown 图片后可追加安全尺寸属性,宽度支持 px 或百分比,高度支持 px。

![图片](https://example.com/a.png){width=420}

![图片](https://example.com/b.png){width=60% height=280}

技术内容

这些语法适合技术文章、长文档和可视化解释。

代码高亮

已支持

代码块会按语言做语法高亮,暂时使用统一代码主题,后续可扩展多套代码主题。

```typescript
const title = "Zaowu";
```

数学公式

已支持

支持 KaTeX 行内公式和块级公式。

$E = mc^2$

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Mermaid 图表

已支持

支持 Mermaid 流程图、时序图等,适合用来解释流程和关系。

```mermaid
graph TD
A[开始] --> B[结束]
```

PlantUML

计划中

PlantUML 适合复杂架构图,当前先列入后续图表能力。

```plantuml
@startuml
Alice -> Bob: hello
@enduml
```

扩展组件

这些是为后续互动文章预留的组件语法。现在不会破坏正文,将来可替换成真实交互组件。

提示组件

已支持

静态提示块已经支持,适合把重点提示、风险提醒、延伸阅读做成组件。

```zaowu-callout
{"tone":"note","title":"提示","body":"这里是一段提示内容。"}
```

空白块

已支持

空白块用于在长文里保留稳定留白,不会被 Markdown 连续空行折叠;默认使用最小留白。

```zaowu-spacer
{"size":"sm"}
```

分栏组件

已支持

分栏块用于把 2-3 张图片或短文本并排展示,窄屏会自动折叠成单列。

```zaowu-columns
{"columns":2,"gap":"md","items":[{"type":"image","src":"https://example.com/a.png","alt":"图 A"},{"type":"image","src":"https://example.com/b.png","alt":"图 B"}]}
```

投票组件

已预留

投票组件已预留入口,接入互动状态后可替换为真实投票。

```zaowu-component
{"type":"poll","id":"topic-poll","title":"你想先看哪个主题?","options":["设计","工程","运营"]}
```

自定义组件

已预留

问卷、互动动画、数据小组件都可以沿相同组件格式继续扩展。

```zaowu-component
{"type":"interactive","id":"demo-motion","title":"交互动画占位"}
```

中文增强语法

计划中

Ruby 注音和 GFM 警告块是参考编辑器里值得补上的中文内容增强能力。

[文字]{注音}

> [!NOTE]
> 这是一条说明。

扩展结构

文章语法会继续为主题、代码样式和互动组件保留扩展空间。

  1. 文章详情页和编辑器预览会保持同一套展示效果。
  2. 正文图片会按横图、竖图和方图自动应用不同的最大宽高,也可以在 Markdown 图片后追加 {width=420} 控制显示尺寸;表格会进入横向滚动容器。
  3. 后续可以按文章主题切换排版、代码样式和组件外观。
  4. Mermaid 和 zaowu-* 组件块会保持独立格式,方便继续增加新的互动内容。
  5. 原始 HTML 会受到限制,文章内容会优先使用安全、可预期的 Markdown 和组件语法。
  6. 登录可读和订阅可读文章会按当前读者状态展示可见正文。

编辑快捷键

文章编辑器支持常见 Markdown 写作快捷键,按钮和键盘会走同一套插入规则。

常用格式

加粗

Ctrl/Cmd+B

包裹或取消 `**文字**`。

斜体

Ctrl/Cmd+I

包裹或取消 `*文字*`。

链接

Ctrl/Cmd+K

插入 Markdown 链接;剪贴板是 URL 时会自动作为链接地址。

保存

Ctrl/Cmd+S

保存或发布当前文章,不触发浏览器保存页面。

块级结构

有序列表

Ctrl/Cmd+Shift+7

给当前行或选中多行添加 / 取消数字列表。

无序列表

Ctrl/Cmd+Shift+8

给当前行或选中多行添加 / 取消项目符号。

引用

Ctrl/Cmd+Shift+9

给当前行或选中多行添加 / 取消引用前缀。

标题

Ctrl/Cmd+Alt+0-6

把当前行切换为 1-6 级标题,0 恢复普通段落。

补充格式

行内代码

Ctrl/Cmd+E

包裹或取消反引号行内代码。

代码块

Ctrl/Cmd+Shift+K

插入 fenced code block,选中文本时会包裹选区。

删除线

Ctrl/Cmd+Shift+X

包裹或取消 `~~文字~~`。

参考差距

参考几个 Markdown 编辑器项目后,先记录当前已补齐和后续可以继续补齐的能力。