# Markdown 格式参考

`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用。

## 转义规则

> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。

### 无条件转义（行内生效，任何位置都要转义）

| 符号 | Markdown 语法用途 | 转义写法 | 示例 |
|------|-------------------|----------|------|
| `\` | 转义符本身 | `\\` | `C:\\Users` → C:\Users |
| `` ` `` | 行内代码 | `` \` `` | `` 用 \` 包裹 `` |
| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 \* 5 = 15 |
| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo\_bar\_baz |
| `[` `]` | 链接文本 | `\[` `\]` | `\[非链接\]` |
| `$` | 数学公式定界 | `\$` | `价格 \$100` |
| `~` | 删除线（GFM `~~text~~`） | `\~` | `a\~\~b\~\~c` → a~~b~~c |
| `<` | XML 标签起始（`<b>`、`<img>` 等会被当作标签解析并生效） | `\<` | 字面量 `<b>` 须写为 `\<b>`；`a < b` 建议写为 `a \< b` |

### 位置敏感转义（仅在特定位置才需要转义）

| 符号 | Markdown 语法用途 | 转义条件 | 示例 |
|------|-------------------|----------|------|
| `#` | 标题 | **仅行首**（去除前导空白后）| 行首 `\# 这不是标题`；行内 `A # B` 无需转义 |
| `+` | 无序列表 | **仅行首**（去除前导空白后）| 行首 `\+ item`；行内 `1 + 2` 无需转义 |
| `-` | 无序列表 / 分隔线 | **仅行首**（去除前导空白后）| 行首 `\- item`；行内 `A - B` 无需转义 |
| `>` | 引用块 | **仅行首**（去除前导空白后）| 行首 `\> 不是引用`；行内 `a > b` 无需转义 |
| `\|` | 表格 cell 分隔 | **仅在 GFM 表格 cell 内** | cell 内 `A \| B`；行内普通文本 `a \| b` 无需转义 |

**不需要转义的场景：**
- 在 `` ` `` 行内代码或 ` ``` ` 代码块内，所有符号均为字面量，无需转义
- `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响

**导出已转义，不要反转义：**
`docs +fetch --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**

**写入时必须转义：**
使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。

**导出 → 更新 工作流示例：**

1. `docs +fetch --api-version v2` 导出得到 `C:\\Users\\test\[1\]`
2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`

自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\]b`，`C:\Users` 应写为 `C:\\Users`。

## Shell 传参
- **首选文件传参**：`--content` 支持 `@path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
- **⚠️ `@file` 路径限制**：`@file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下（如 `./_content.md`），用完自行清理。
- **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
- **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
- **`$'...'` ANSI-C 引号**：按 C 转义解析，`\n`=换行、`\\`=单个 `\`；**zsh 下未知转义（如 `\<`）的 `\` 会被吞**，要保留字面 `\` 必须写 `\\`。只在确实需要 `\n`/`\t` 时用
- **多行内容**：用 `<<'EOF'` heredoc，EOF 必须带引号，否则仍展开 `$`
- **`\n` 在 `'...'` 和 `"..."` 里都是字面量**，不是换行；要真换行用 `$'...\n...'` 或 heredoc

## 图片语法

Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
```markdown
![alt text](https://example.com/photo.png)
```
- `alt text` 为图片描述（可选，可留空）
- URL 支持 `http://` 和 `https://` 协议
- 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`

## Markdown 不支持的 Block 类型

非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。
> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。

## 参考

- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范