Markdown 语法支持
条目笔记（Item Note）同时存在于两个地方：作为 Markdown 存在你的 vault 里，同时 作为一条 Zotero 笔记存在。每次同步都要在两者之间转换。
Zotero 的笔记格式是一套固定的积木——段落、标题、列表、表格、链接、几种文字样式。 Obsidian 的 Markdown 比它大，而且 Obsidian 还在上面加了自己的语法。所以对每一种 写法，转换都必须决定：当一方无法表达另一方刚说的东西时，该怎么办。
这一页把这些决定全部写清楚，这样你就不必靠丢东西来发现它们。
怎么读这一页
所有情况归为三类：
| 结果 | 含义 |
|---|---|
| 保持不变 | 原样回来，和你写的一模一样。 |
| 格式被规范化 | 还是同一篇文档，只是写法变了。没有任何丢失，你只会看到一次性的差异。 |
| 不支持 | 含义改变，或者内容消失。下面都附了替代做法。 |
如果只读一节，读不支持。
保持不变
以下内容往返后完全不变。
Obsidian 语法
| 你写的 | 说明 |
|---|---|
[[笔记]]、[[笔记|别名]] | 包括 [[笔记#标题]]、[[笔记#^块ID]]、[[#标题]] |
![[笔记]]、![[图片.png]] | 包括 ![[图片.png|400]]、![[图片.png|400x260]]、![[文档.pdf#page=3]] |
#标签、#多级/标签 | 行首和句中都可以 |
^块ID | 块引用标识符 |
==高亮== | |
> [!note] 标注框（callout） | 包括标题、折叠（[!note]- / [!note]+）和嵌套 |
^[行内脚注] | 可以跨行折行 |
[^1] 和 [^1]: 定义 | |
%%注释%% 和 %% 注释块 |
标准 Markdown
| 你写的 | 说明 |
|---|---|
# … ###### | |
**粗体**、*斜体*、~~删除线~~ | |
`代码` 和围栏代码块 | 围栏内部的内容永远不会被改动——见天生安全 |
> 引用 | 包括嵌套 |
| 列表、嵌套列表 | |
- [x] / - [ ] 任务 | 包括嵌套任务 |
| 表格 | 包括对齐方式和转义竖线（|） |
$公式$ 和 $$公式$$ | |
[文字](链接)、裸 URL、 | |
<u>、<sub>、<sup> | 内部嵌套的格式也会保留 |
| Emoji、中日韩文字、从右到左文字 | 包括 👨👩👧👦 这类组合 emoji |
Zotero 自己的内容
在 Zotero 里创建的引用、高亮、标注和彩色文字都会被完整保留，包括让它们在 Zotero 里可点击的那些隐藏数据。在 Obsidian 里编辑周围的文字不会破坏它们。
格式被规范化
以下写法回来后含义完全相同，只是拼写方式变了。第一次同步后你会看到一次差异， 之后就稳定了。
- 项目 → * 项目 列表符号
--- → *** 分隔线
标题 → # 标题 "下划线式"标题变成 # 式
=====
>> 引用 → > > 引用 嵌套引用的空格
<https://x> → https://x 裸链接保持裸的
& → & HTML 实体被解析
[a][ref] → [a](url) 引用式链接变成直接链接
[ref]: url
表格还会被填充空格以对齐列：
| A | B | | A | B |
| --- | --- | → | -------------- | ------ |
| 较长的内容 | b | | 较长的内容 | b |
单个换行会不会变成可见的折行，取决于 Obsidian 的严格换行设置 （设置 → 编辑器）。ZotFlow 会读取这个设置并让两个方向保持一致，所以你不需要做 任何事——但两种模式下的输出确实不同。
不支持
下面这些都受限于「一条 Zotero 笔记能装下什么」。如果你确实需要它们，办法是把内容 放在 Zotero 笔记之外，同时仍留在同一个文件里：
- Source Note 里的 persist region——仅存本地、 永不同步到 Zotero，且每次重新渲染都原样保留。这样内容仍然和条目待在一起， 而单独开一篇笔记做不到这一点；
- Source Note 自己的 frontmatter，那部分始终归你编辑；
- 或者一篇普通的 vault 笔记，如果内容本来就不属于某个具体条目。
只有条目笔记和标注评论会经过 Zotero 格式的往返转换。
代码块的语言标注
你写的 ```python 同步后 ```
code() code()
``` ```
代码本身是安全的，只有语言名字会丢失。Zotero 的笔记格式没有地方存放它。
最明显的后果：```mermaid 图表不再渲染成图，而是显示源码。
建议做法：把图表放进 Source Note 的 persist region，那里的内容不会被转换。 除此之外你损失的只有 Obsidian 里的语法高亮，而且只在条目笔记里。
YAML frontmatter
你写的 --- 同步后 （被破坏）
title: 我的笔记
---
Frontmatter 属于 vault 笔记，不属于 Zotero 笔记——Zotero 没有地方存它。条目笔记 里不应该包含 frontmatter。
建议做法：用 Source Note 自己的 frontmatter——那部分始终归你编辑，也从不会 被发送到 Zotero。
自定义复选框状态
你写的 - [x] 完成 同步后 - [x] 完成
- [/] 进行中 - \[/] 进行中
标准的 - [x] 和 - [ ] 任务没问题。来自 Tasks 社区插件的扩展状态
（[/]、[?]、[-]、[>]、[!]、["]）回来时会带一个反斜杠，插件不再把它
识别为状态。
没有任何内容被销毁——文字还在，也还读得懂——只是插件看不到状态了。
建议做法：条目笔记里用标准复选框。如果你依赖自定义状态，把那份清单放进 persist region。
未被使用的链接定义
你写的 见[手册][m]。 同步后 见[手册](https://x)。
[m]: https://x
[没用到]: https://y （整行被删除）
被使用的定义没问题——链接只是变成了直接写法，指向的地方完全相同。
没有任何地方引用的定义会被删除。如果你习惯在笔记底部囤一批链接定义留着 以后用，它们不会存活。
建议做法：条目笔记里直接写 [文字](链接)。
目标里含 * 或反引号的 wikilink
你写的 [[我的*笔记*名]] 同步后 \[\[我的*笔记*名]]
Markdown 会先把 *笔记* 读成斜体，ZotFlow 根本没机会看到完整的链接，所以拼不
回来。
下划线不受影响——[[snake_case_笔记]] 没问题，因为 Markdown 不会把词内的
下划线当作斜体。
建议做法：被链接的笔记标题里避免使用 * 和反引号。其余标点几乎都没问题，
包括 &、_、~、(、) 以及非拉丁文字。
表格单元格里、公式内部的 |
你写的（在 Zotero 里） | $a|b$ | second |
同步后 整行被切开，最后一格丢失
这一种只可能发生在 Zotero 编辑器里写的公式上——Markdown 表达不出来，因为那个
| 会先结束单元格。在表格里 | 是列分隔符，而公式内容一旦转义就会被破坏。
建议做法：表格里的公式如果需要竖线，写成 \vert 或 \mid。
天生安全
有几件事值得单独说明，因为大家常常会担心。
代码块和行内代码里的任何内容都不会被改动。 一篇讲解 Markdown 语法的笔记 ——里面有 wikilink、callout、任务语法、嵌入、标签示例——会逐字节原样回来：
```markdown
[[wikilink]] 这些是示例，不是链接
![[embed.png]] 它们会一直是示例
> [!note]
- [x] task
#tag
```
Zotero 的引用和标注被完整保留，包括背后的数据。在 Obsidian 里编辑引用周围的 文字不会破坏它。
非拉丁文字、emoji 和从右到左的文字原样往返，包括组合 emoji 和生僻字符。
反复同步不会累积变化。 除了上面说的一次性规范化，一篇不再编辑的笔记在任意 多次同步后都保持逐字节相同。
发现了别的问题
如果你发现某种语法会变化、而这一页上没有列出，那就是一个值得反馈的 bug——上面的 清单力求完整。反馈时请附上你写的内容和拿回来的内容。