### wrap_editable region examples

Source: https://zotflow.peterduan.dev/template-filters

Examples for note, annotation comment, and persist regions using wrap_editable. Annotation comments undergo lightweight conversion before entering context.

```liquid
{{ note.note | html2md | wrap_editable: "NOTE", note.key }}
```

```liquid
{{ annotation.comment | wrap_editable: "ANNO", annotation.key }}
```

```liquid
{{ "Write your thoughts here…" | wrap_editable: "PERSIST", "summary" }}
```

--------------------------------

### Example Footnote Reference Template marker

Source: https://zotflow.peterduan.dev/releases/1.2.1

Example marker pattern for the Footnote Reference Template. Ensure your definition template uses the same marker to keep references aligned.

```handlebars
[^{{ item.citationKey | default: item.key }}]  
```

--------------------------------

### Render bibliographies with the bibliography filter

Source: https://zotflow.peterduan.dev/template-filters

Examples of rendering bibliographies for items or lists of items using the bibliography filter.

```liquid
{{ items | bibliography }}  

{{ items | bibliography: style: "apa", join: "\n\n" }}  

{{ item  | bibliography: "ieee" }}             →  [1] A. Author, …
```

--------------------------------

### Markdown syntax preservation examples

Source: https://zotflow.peterduan.dev/markdown-support

Demonstrates that Markdown syntax elements like wikilinks, embeds, callouts, tasks, and tags are preserved exactly as written.

```markdown
[[wikilink]]        these are examples, not links

![[embed.png]]      and they stay examples

> [!note]

- [x] task

#tag
```

--------------------------------

### Basic Citation and Bibliography Filter Usage

Source: https://zotflow.peterduan.dev/csl-citations

Examples of using the citation and bibliography filters in templates to produce formatted output.

```liquid
{{ item | citation }}                     →  (Doe, 2020)  

{{ annotation | citation }}               →  (Doe, 2020, p. 5)  

{{ items | bibliography: style: "apa" }}  →  a full, correctly sorted bibliography
```

--------------------------------

### Render citations with the citation filter

Source: https://zotflow.peterduan.dev/template-filters

Examples of rendering citations using the citation filter with various arguments like style, locale, and format.

```liquid
{{ item | citation }}                          →  (Doe, 2020)  

{{ item | citation: "ieee" }}                  →  [1]           (positional arg = style id)  

{{ item | citation: style: "apa", locale: "de-DE", format: "text" }}  

{{ items | citation }}                         →  (Doe, 2020; Roe, 2021)
```

--------------------------------

### Markdown Syntax Normalization Examples

Source: https://zotflow.peterduan.dev/markdown-support

Examples of how ZotFlow reformats markdown syntax elements such as list markers, horizontal rules, headings, quotes, URLs, HTML entities, and reference links.

```markdown
- item          →   * item            list markers  

---             →   ***               horizontal rules  

Title           →   # Title           "underline" headings become #  

=====  

>> quote        →   > > quote         nested quote spacing  

<https://x>     →   https://x         plain URLs stay plain  

&amp;           →   &                 HTML entities resolve  

[a][ref]        →   [a](url)          reference links become direct links  

[ref]: url
```

--------------------------------

### Render annotation citations

Source: https://zotflow.peterduan.dev/template-filters

Examples of using the citation filter with annotations to automatically include page locators.

```liquid
{{ annotation | citation }}                    →  (Doe, 2020, p. 5)  

{{ annotations | citation }}                   →  (Doe, 2020, p. 5; Roe, 2021, p. 12)
```

--------------------------------

### Related-works list bibliography

Source: https://zotflow.peterduan.dev/template-filters

Example of rendering a bibliography for related items using a conditional block.

```liquid
{% assign cited = item.relatedItems | where: "resolved", true %}  

{% if cited.size > 0 %}  

## References  

{{ cited | bibliography: style: "apa" }}  

{% endif %}
```

--------------------------------

### Numbered style footnote workflow

Source: https://zotflow.peterduan.dev/template-filters

Example of stripping the numbering from a bibliography entry for use in Obsidian footnotes.

```liquid
[^{{ item.citationKey }}]: {{ item | bibliography: "ieee" | remove_first: "[1] " }}
```

--------------------------------

### Footnote workflow with citation filter

Source: https://zotflow.peterduan.dev/template-filters

Example of using the citation filter to generate a footnote body for note-class styles.

```liquid
[^{{ item.citationKey }}]: {{ item | citation: "chicago-note-bibliography" }}
```

--------------------------------

### Encode annotation JSON

Source: https://zotflow.peterduan.dev/template-filters

Example of using the process_raw_anno_json filter to encode annotation data for comment markers.

```liquid
{{ annotation.raw | process_raw_anno_json }}
```

--------------------------------

### 附件链接（默认打开方式与 Zotero 本地阅读器）

Source: https://zotflow.peterduan.dev/template-guide

生成指向附件的 Markdown 链接，默认打开 Obsidian 内部附件；若要使用 Zotero 原生阅读器打开，需传递参数 `"zotero"`。

```Liquid
- [{{ attachment.filename }}]({{ attachment | attachment_link }})

---

要在 Zotero 的本地阅读器中打开：

- [{{ attachment.filename }}]({{ attachment | attachment_link: "zotero" }})
```

--------------------------------

### 渲染标签（YAML Frontmatter）

Source: https://zotflow.peterduan.dev/template-guide

以 YAML 数组格式列出所有标签，并用下划线替换空格以便用于 Obsidian 文件属性。

```Liquid
tags: [{% for t in item.tags %}"#{{ t.tag | replace: " ", "_" }}"{% unless forloop.last %}, {% endunless %}{% endfor %}]
```

--------------------------------

### Apply default frontmatter with ?? prefix

Source: https://zotflow.peterduan.dev/releases/1.6.0

Use the ?? prefix in template keys to provide a default value that does not overwrite existing user-maintained values. The prefix is stripped during rendering, and keys without it continue to refresh from the template.

```yaml
---

??rating: unrated

status: reviewed

---
```

--------------------------------

### 注解链接（跳到特定注解）

Source: https://zotflow.peterduan.dev/template-guide

生成一个 ZotFlow callout，标题中包含注解类型和颜色，链接跳转到具体注解。使用 Zotero 本地阅读器版本时去掉 callout 前缀。

```Liquid
> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ attachment.filename }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link }})


```

```Liquid
[{{ attachment.filename }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link: "zotero" }})
```

--------------------------------

### 按附件分组注解

Source: https://zotflow.peterduan.dev/template-guide

这是一个多行 Liquid 循环，遍历附件的所有注解，按附件文件名分组列出。

```Liquid
{%- for attachment in item.attachments -%}

{%- if attachment.annotations.length > 0 -%}

### {{ attachment.filename }}

{%- for annotation in attachment.annotations -%}

- p.{{ annotation.pageLabel }}: {{ annotation.text }}

{%- endfor -%}

{%- endif -%}

{%- endfor -%}
```

--------------------------------

### 内联注释 callout 中的标签

Source: https://zotflow.peterduan.dev/template-guide

若注解有标签，则生成一个引用块，其中包含用#号开头的标签，并用空格分隔。

```Liquid
{% if annotation.tags and annotation.tags.length > 0 -%}

> {% for t in annotation.tags %}#{{ t.tag | replace: " ", "_" }}{% unless forloop.last %} {% endunless %}{% endfor %}

{%- endif %}
```

--------------------------------

### 路径模板

Source: https://zotflow.peterduan.dev/template-guide

使用 collection 路径生成目录结构，若没有路径则默认使用“Unsorted”，若没有 citationKey 则使用默认的 key。示例输出：`References/Research/Machine Learning/@smith2024`。

```Liquid
References/{{ itemPaths[0] | default: "Unsorted" }}/@{{ citationKey | default: key }}
```

--------------------------------

### 安全的 YAML 值（json 过滤器）

Source: https://zotflow.peterduan.dev/template-guide

对可能包含特殊字符的字符串使用 `json` 过滤器，以避免 YAML 解析错误。

```Liquid
title: {{ item.title | json }}
```

--------------------------------

### 注解 Callout 容器

Source: https://zotflow.peterduan.dev/template-guide

生成一个包含注解类型和颜色信息的 callout，内部可嵌入引用块。可通过 CSS 自定义每个 callout 样式。

```Liquid
> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] Title text

> > Quoted annotation text
```

--------------------------------

### Citation Filter with Style Override

Source: https://zotflow.peterduan.dev/csl-citations

Demonstrates using the citation filter with a default call and a per-call style override.

```liquid
{{ item | citation }}  

{{ item | citation: "ieee" }}          {%- comment %} per-call style override {% endcomment %}
```

--------------------------------

### 逗号分隔的创作者列表

Source: https://zotflow.peterduan.dev/template-guide

生成一个包含所有创作者名称并用逗号分隔的字符串，常用于 frontmatter 的 authors 字段。

```Liquid
authors: [{% for c in item.creators %}"{{ c.name }}"{% unless forloop.last %}, {% endunless %}{% endfor %}]
```

--------------------------------

### Markdown Table Padding Normalization

Source: https://zotflow.peterduan.dev/markdown-support

Demonstrates how ZotFlow pads markdown table columns to ensure they line up correctly.

```markdown
| A | B |          | A              | B      |  

| --- | --- |  →   | -------------- | ------ |  

| longer | b |     | longer         | b      |
```

--------------------------------

### Footnote Reference Template

Source: https://zotflow.peterduan.dev/template-variables

Template for generating inline footnote markers.

```liquid

[^{{ item.citationKey | default: item.key }}]  


```

--------------------------------

### Before fix: mismatched footnote markers

Source: https://zotflow.peterduan.dev/releases/1.2.1

Shows the previous behavior where the reference marker [^smith2024-p13] did not match the definition marker [^smith2024], causing Obsidian to fail connecting them.

```markdown
lorem ipsum[^smith2024-p13]  

  

[^smith2024]: <reference> ← didn't match  
```

--------------------------------

### 提取年份（slice 过滤器）

Source: https://zotflow.peterduan.dev/template-guide

从日期字段中提取前四个字符作为年份。适用于在 YAML frontmatter 中为年份字段赋值。

```Liquid
year: {{ item.date | slice: 0, 4 }}

```

--------------------------------

### 相关项（三叉分支）

Source: https://zotflow.peterduan.dev/template-guide

显示相关项列表，对具有 Source Note 路径的项使用 wikilink，对仅在本地存在的项显示标题和 key，对未同步/跨库项仅显示 key 并标注“not synced”。

```Liquid
{%- if item.relatedItems.size > 0 -%}

## Related

{% for rel in item.relatedItems -%}

{% if rel.notePath -%}

- [[{{ rel.notePath }}|{{ rel.title }}]]

{%- elsif rel.title -%}

- {{ rel.title }} (`{{ rel.key }}`)

{%- else -%}

- `{{ rel.key }}` *(not synced)*

{%- endif %}

{% endfor -%}

{%- endif -%}
```

--------------------------------

### 在块引用中显示多行文本

Source: https://zotflow.peterduan.dev/template-guide

将 item.abstractNote 中的换行符替换为块引用前缀，使多行文本正确显示在块引用中。

```Liquid
{%- capture quote_string %}{{ newline }}> {% endcapture -%}

> {{ item.abstractNote | replace: newline, quote_string }}
```

--------------------------------

### 使用扁平化的 attachmentAnnotations

Source: https://zotflow.peterduan.dev/template-guide

遍历样本中的 `item.attachmentAnnotations` 字段，为每个注解输出文本及颜色。

```Liquid
{%- for annotation in item.attachmentAnnotations -%}

- {{ annotation.text }} ({{ annotation.color }})

{%- endfor -%}
```

--------------------------------

### Default Local Source Note Template

Source: https://zotflow.peterduan.dev/template-variables

The default template for local source notes. It outputs a YAML frontmatter with locked and attachment fields, then renders the item basename and annotations. Annotation comments are wrapped in editable regions using the wrap_editable filter, while read-only annotations are rendered as plain locked text. The template uses Liquid syntax and includes conditional logic for annotation types and tags.

```Liquid
---  

zotflow-locked: {{true}}  

zotflow-local-attachment: [[{{ path }}]]  

---  

{%- capture quote_string %}{{ newline }}> {% endcapture -%}  

{%- capture quote_string_2 %}{{ newline }}> >{% endcapture -%}  

# {{ item.basename }}  

{%- if item.annotations.length > 0 -%}  

## Annotations  

{%- for annotation in item.annotations -%}  

  

> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [[{{item.path}}#page={{ annotation.pageLabel }}#annotation={{ annotation.key | process_nav_info }}|{{ item.name }}, p.{{ annotation.pageLabel }}]]  

{%- if annotation.type == "ink" or annotation.type == "image"-%}  

> > ![[{{settings.annotationImageFolder}}/{{ annotation.key }}.png]]  

{%- else -%}  

> > {{ annotation.text | replace: newline, quote_string_2 }}  

{%- endif -%}  

>  

> {{ annotation.comment | wrap_editable: "ANNO", annotation.key | replace: newline, quote_string }}  

{%- if annotation.tags and annotation.tags.length > 0 -%}  

>  

> {% for t in annotation.tags %}#{{ t.tag | replace: " ", "_" }}{% unless forloop.last %} {% endunless %}{% endfor %}  

{%- endif -%}  

^{{ annotation.key }}  

  

{%- endfor -%}  

{%- endif -%}  


```

--------------------------------

### Zotero Tree View representation of Item Notes

Source: https://zotflow.peterduan.dev/item-notes

Visual representation of how child notes appear as leaf nodes under a parent item in the Zotero Tree View.

```text
📚 My Library  

└── 📄 Smith et al. (2024) — Distributed Tracing  

    ├── 📎 smith2024.pdf  

    ├── 📝 Open questions  

    └── 📝 Summary  
```

--------------------------------

### Template: Link to an attachment opening in Zotero

Source: https://zotflow.peterduan.dev/releases/1.1.0

Pass the argument "zotero" to the attachment_link filter to open the attachment in the Zotero desktop app instead of ZotFlow.

```markdown
- [{{ attachment.filename }}]({{ attachment | attachment_link: "zotero" }})
```

--------------------------------

### Template: Annotation callout linking to the exact annotation

Source: https://zotflow.peterduan.dev/releases/1.1.0

Creates a callout that links to the annotation in the PDF, opening in ZotFlow's reader by default.

```markdown
> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ attachment.filename }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link }})
```

--------------------------------

### 条件显示 DOI

Source: https://zotflow.peterduan.dev/template-guide

仅当存在 DOI 时，才生成带链接的 DOI 行。通过条件判断避免空值。

```Liquid
{%- if item.DOI -%}

DOI: [{{ item.DOI }}](https://doi.org/{{ item.DOI }})

{%- endif -%}
```

--------------------------------

### item_link filter usage

Source: https://zotflow.peterduan.dev/template-filters

Generates a clickable link to an item. Default produces a ZotFlow protocol URI; pass "zotero" for a native Zotero URI. Applies to Zotero Source Note.

```liquid
{{ item | item_link }}  

{{ related | item_link: "zotero" }}  
```

--------------------------------

### Legacy custom Footnote Definition Template (before)

Source: https://zotflow.peterduan.dev/releases/1.2.1

Legacy template that outputs only the body without the [^marker]: prefix. ZotFlow will prepend a marker derived from the rendered reference, but updating is recommended.

```handlebars
{{ item.creators[0].name }}, *{{ item.title }}*, {{ item.year }}  
```

--------------------------------

### process_nav_info filter usage

Source: https://zotflow.peterduan.dev/template-filters

Converts an annotation key into a URL-encoded JSON navigation parameter for obsidian://zotflow deep links. Applies to all template types.

```liquid
{{ annotation.key | process_nav_info }}  
```

--------------------------------

### Pandoc Citation Template

Source: https://zotflow.peterduan.dev/template-variables

Template for generating Pandoc-style citations with optional annotation page numbers.

```liquid

[@{{ item.citationKey | default: item.key }}{% if annotations.size > 0 %}{% assign pages = annotations | map: 'pageLabel' | compact | uniq | join: ', ' %}{% if pages != empty %}, pp. {{ pages }}{% endif %}{% endif %}]  


```

--------------------------------

### Define a Persist Region with Comment Markers

Source: https://zotflow.peterduan.dev/source-notes

Use the ZF_PERSIST_BEG and ZF_PERSIST_END comment markers to define a region that ZotFlow will preserve during note updates.

```markdown
## My Summary  

<!-- ZF_PERSIST_BEG_summary -->  

  

<!-- ZF_PERSIST_END_summary -->
```

--------------------------------

### Updated custom Footnote Definition Template (after)

Source: https://zotflow.peterduan.dev/releases/1.2.1

Updated template that includes the [^marker]: prefix, using item.citationKey with a fallback to item.key. This ensures the definition marker matches the reference template.

```handlebars
[^{{ item.citationKey | default: item.key }}]: {{ item.creators[0].name }}, *{{ item.title }}*, {{ item.year }}  
```

--------------------------------

### Template: Link to an attachment

Source: https://zotflow.peterduan.dev/releases/1.1.0

Use in custom templates to create a link to an attachment that opens in ZotFlow's reader by default.

```markdown
- [{{ attachment.filename }}]({{ attachment | attachment_link }})
```

--------------------------------

### Wikilink Citation Template

Source: https://zotflow.peterduan.dev/template-variables

Template for generating wikilinks to source notes, optionally linking to specific annotations.

```liquid

{%- if annotations.size > 0 -%}  

{%- for annotation in annotations -%}  

[[{{ notePath }}#^{{ annotation.key }}|{{ item.creators[0].name | default: "Unknown" }} ({{ item.date | slice: 0, 4 }}), p. {{ annotation.pageLabel }}]]  

{%- if forloop.last == false %}, {% endif -%}  

{%- endfor -%}  

{%- else -%}  

[[{{ notePath }}|{{ item.creators[0].name | default: "Unknown" }} ({{ item.date | slice: 0, 4 }})]]  

{%- endif -%}  


```

--------------------------------

### Template: Link to a related item's note

Source: https://zotflow.peterduan.dev/releases/1.1.0

Creates a link to the source note of a related item using the item_link filter.

```markdown
Related: [{{ related.title }}]({{ related | item_link }})
```

--------------------------------

### After fix: matching footnote markers

Source: https://zotflow.peterduan.dev/releases/1.2.1

Shows the corrected behavior where the reference and definition use the same marker [^smith2024-p13], ensuring they are connected.

```markdown
lorem ipsum[^smith2024-p13]  

  

[^smith2024-p13]: <reference> ← matches  
```

--------------------------------

### Unused link definitions are deleted after sync

Source: https://zotflow.peterduan.dev/markdown-support

Shows that used link definitions become direct links, while unused definitions are deleted. Write links directly as [text](url) in Item Notes to avoid losing definitions.

```markdown
you write        See [the manual][m].     after sync   See [the manual](https://x).  

                 [m]: https://x  

  

                 [unused]: https://y                   (line deleted)  


```

--------------------------------

### Render CSL citations and bibliography with Liquid filters

Source: https://zotflow.peterduan.dev/releases/1.3.0

Use these Liquid filters in templates to render CSL citations and bibliographies. The citation filter on an item produces a parenthetical reference, while on an annotation it includes the page label as a CSL locator. The bibliography filter accepts a style parameter, e.g. "apa", and outputs a full sorted bibliography.

```liquid
{{ item | citation }}                     →  (Doe, 2020)  
```

```liquid
{{ annotation | citation }}               →  (Doe, 2020, p. 5)  
```

```liquid
{{ items | bibliography: style: "apa" }}  →  a full, correctly sorted bibliography  
```

--------------------------------

### Declare a persist region in a template

Source: https://zotflow.peterduan.dev/releases/1.3.0

Use the ZF_PERSIST_BEG and ZF_PERSIST_END markers to define a region where content survives template re-renders.

```markdown

## My Summary  

<!-- ZF_PERSIST_BEG_summary -->  

  

<!-- ZF_PERSIST_END_summary -->  



```

--------------------------------

### YAML frontmatter is mangled after sync

Source: https://zotflow.peterduan.dev/markdown-support

Shows that YAML frontmatter in an Item Note is mangled after sync because Zotero has no place to store it. Use the Source Note's own frontmatter instead, which is never sent to Zotero.

```markdown
you write        ---                after sync    (mangled)  

                 title: My note  

                 ---  


```

--------------------------------

### Render related items in ZotFlow note template

Source: https://zotflow.peterduan.dev/releases/1.0.10

Use in a ZotFlow library source note template to render a Related section. Iterates over `item.relatedItems`, emitting a wikilink when `rel.notePath` exists, a plain title with key when only `rel.title` is present, and a fallback placeholder for unsynced items. Requires the related item to be resolved in the local database for `notePath` and `title` to be available.

```jinja
{%- if item.relatedItems.size > 0 -%}  

## Related  

  

{% for rel in item.relatedItems -%}  

{% if rel.notePath -%}  

- [[{{ rel.notePath }}|{{ rel.title }}]]  

{%- elsif rel.title -%}  

- {{ rel.title }} (`{{ rel.key }}`)  

{%- else -%}  

- `{{ rel.key }}` *(not synced)*  

{%- endif %}  

{% endfor -%}  

{%- endif -%}  


```

--------------------------------

### annotation_link filter usage

Source: https://zotflow.peterduan.dev/template-filters

Generates a clickable link to navigate to a specific annotation. Default produces a ZotFlow protocol URI; pass "zotero" for a native Zotero URI. Applies to Zotero Source Note.

```liquid
{{ annotation | annotation_link }}  

{{ annotation | annotation_link: "zotero" }}  
```

--------------------------------

### attachment_link filter usage

Source: https://zotflow.peterduan.dev/template-filters

Generates a clickable link to open an attachment. Default produces a ZotFlow protocol URI; pass "zotero" for a native Zotero URI. Applies to Zotero Source Note.

```liquid
{{ attachment | attachment_link }}  

{{ attachment | attachment_link: "zotero" }}  
```

--------------------------------

### Template: Local annotation callout opening in ZotFlow

Source: https://zotflow.peterduan.dev/releases/1.1.0

For local attachment templates, use annotation_link to open the annotation in ZotFlow's reader. item_link does not apply to local attachments.

```markdown
> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ item.name }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link }})
```

--------------------------------

### Footnote Definition Template

Source: https://zotflow.peterduan.dev/template-variables

Template for generating the full footnote definition at the end of a document, including author and title formatting.

```liquid

{%- if item.creators.length > 1 -%}  

{{ item.creators[0].name }} et al.  

{%- elsif item.creators.length == 1 -%}  

{{ item.creators[0].name }}  

{%- else -%}  

Unknown Author  

{%- endif -%}, *{{ item.title }}* ({{ item.date | slice: 0, 4 }}).  


```

--------------------------------

### Default ZotFlow Template

Source: https://zotflow.peterduan.dev/template-variables

The built-in template used by ZotFlow for rendering Zotero items. It includes frontmatter, abstract, attachment links, notes, and annotation callouts.

```liquid
---

citationKey: {{ item.citationKey | json }}

title: {{ item.title | json }}

itemType: {{ item.itemType | json }}

creators: [{% for c in item.creators %}"{{ c.name }}"{% unless forloop.last %}, {% endunless %}{% endfor %}]

publication: {{ item.publicationTitle | default: item.publisher | json }}

date: {{ item.date | json }}

year: {{ item.year }}

url: {{ item.url | json }}

doi: {{ item.DOI | json }}

tags: [{% for t in item.tags %}"#{{ t.tag | replace: " ", "_" }}"{% unless forloop.last %}, {% endunless %}{% endfor %}]

---

{%- capture quote_string %}{{ newline }}> {% endcapture -%}

{%- capture quote_string_2 %}{{ newline }}> >{% endcapture -%}

# {{ item.title }}

{%- if item.abstractNote -%}

## Abstract

> {{ item.abstractNote | replace: newline, quote_string }}

  

{%- endif -%}

{%- if item.attachments.length > 0 -%}

## Attachments

{%- for attachment in item.attachments -%}

- [{{ attachment.filename }}]({{ attachment | attachment_link }})

{%- endfor -%}

  

{%- endif -%}

## Notes

{%- if item.notes.length > 0 -%}

{%- for note in item.notes -%}

{{ note.note | html2md | wrap_editable: "NOTE", note.key }}

  

{%- endfor -%}

{%- endif -%}

{%- if item.attachments.length > 0 and item.attachmentAnnotations.length > 0 -%}

## Annotations

{%- for attachment in item.attachments -%}

{%- if attachment.annotations.length > 0 -%}

### {{ attachment.filename }}

{%- for annotation in attachment.annotations -%}

> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ attachment.filename }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link }})

{%- if annotation.type == "ink" or annotation.type == "image"-%}

> > ![[{{settings.annotationImageFolder}}/{{ annotation.key }}.png]]

{%- else -%}

> > {{ annotation.text | replace: newline, quote_string_2 }}

{%- endif -%}

>  

> {{ annotation.comment | wrap_editable: "ANNO", annotation.key | replace: newline, quote_string }}

> {% if annotation.tags and annotation.tags.length > 0 -%} {% for t in annotation.tags %}#{{ t.tag | replace: " ", "_" }}{% unless forloop.last %} {% endunless %}{% endfor %} {%- endif %}

^{{ annotation.key }}

  

{%- endfor -%}

{%- endif -%}

{%- endfor -%}

{%- endif -%}

{%- if item.attachments.length == 0 and item.itemType == "attachment" and item.annotations.length > 0 -%}

## Annotations

{%- for annotation in item.annotations -%}

> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ item.title }}, p.{{ annotation.pageLabel }}]({{ annotation | annotation_link }})

{%- if annotation.type == "ink" or annotation.type == "image"-%}

> > ![[{{settings.annotationImageFolder}}/{{ annotation.key }}.png]]

{%- else -%}

> > {{ annotation.text | replace: newline, quote_string_2 }}

{%- endif -%}

>  

> {{ annotation.comment | wrap_editable: "ANNO", annotation.key | replace: newline, quote_string }}

> {% if annotation.tags and annotation.tags.length > 0 -%} {% for t in annotation.tags %}#{{ t.tag | replace: " ", "_" }}{% unless forloop.last %} {% endunless %}{% endfor %} {%- endif %}

^{{ annotation.key }}

  

{%- endfor -%}

{%- endif -%}
```

--------------------------------

### Add Editable Regions to Item Notes

Source: https://zotflow.peterduan.dev/releases/0.6.0

Use the wrap_editable filter in your library source note template to enable editing for Zotero child notes.

```jinja2
{%- if item.notes.length > 0 -%}  

{%- for note in item.notes -%}  

{{ note.note | html2md | wrap_editable: "NOTE", note.key }}  

  

{%- endfor -%}  

{%- endif -%}
```

--------------------------------

### Accessing Raw CSL-JSON Data

Source: https://zotflow.peterduan.dev/csl-citations

Templates can access the raw CSL-JSON data directly using the item object.

```liquid
{{ item.csljson.title }}
```

--------------------------------

### Manual persist region markers

Source: https://zotflow.peterduan.dev/template-filters

Hand-written marker pair for a persist region. Persist regions are local-only and never synced to Zotero. Id must be unique within a note and stable across renders.

```markdown
## My Summary  

<!-- ZF_PERSIST_BEG_summary -->  

  

<!-- ZF_PERSIST_END_summary -->  
```

--------------------------------

### html2md filter usage

Source: https://zotflow.peterduan.dev/template-filters

Converts Zotero HTML (ProseMirror format) to Markdown. Handles math, code blocks, tables, images, and wrapper div attributes. Async filter; almost always chained with wrap_editable. Applies to Zotero Source Note.

```liquid
{{ note.note | html2md | wrap_editable: "NOTE", note.key }}  
```

--------------------------------

### wrap_editable filter usage

Source: https://zotflow.peterduan.dev/template-filters

Wraps content in hidden HTML comment markers for editable regions. TYPE can be "NOTE", "ANNO", or "PERSIST". Applies to Zotero Source Note and Local Source Note (local: "ANNO" and "PERSIST" only).

```liquid
{{ value | wrap_editable: "TYPE", key }}  
```

--------------------------------

### Embed Format Output

Source: https://zotflow.peterduan.dev/citation-guide

The Embed format generates an Obsidian block-embed pointing to a specific annotation block ID. This requires the Source Note to exist and contain the corresponding block ID.

```markdown
![[Source/@smith2024#^annotationKey]]
```

--------------------------------

### Code block language name is dropped after sync

Source: https://zotflow.peterduan.dev/markdown-support

Shows that the language name after the opening triple backticks is dropped when an Item Note is synced to Zotero, leaving only the code block. The code itself is preserved, but syntax highlighting is lost.

```markdown
you write        ```python          after sync    ```  

                 code()                           code()  

                 ```                              ```  


```

--------------------------------

### Custom checkbox statuses are escaped after sync

Source: https://zotflow.peterduan.dev/markdown-support

Shows that standard checkboxes survive sync, but custom statuses from the Tasks plugin ([/], [?], [-], [>], [!], ["]) come back with a backslash and are no longer recognized as statuses. Use standard checkboxes in Item Notes or keep custom statuses in a persist region.

```markdown
you write        - [x] done         after sync    - [x] done  

                 - [/] started                    - \[/] started  


```

--------------------------------

### Wikilinks with asterisks or backticks are escaped

Source: https://zotflow.peterduan.dev/markdown-support

Shows that wikilinks containing asterisks or backticks are escaped after sync because Markdown interprets the asterisks as italics. Avoid these characters in note titles; underscores are fine.

```markdown
you write        [[my*note*name]]     after sync    \[\[my*note*name]]  


```

--------------------------------

### Vertical bar in maths inside a table splits the row

Source: https://zotflow.peterduan.dev/markdown-support

Shows that a vertical bar inside maths within a table splits the row and loses the last cell. Use \vert or \mid in formulas inside tables to avoid this.

```markdown
you write (in Zotero)    | $a|b$ | second |  

after sync               the row is split and the last cell is lost  


```

--------------------------------

### Add Editable Regions to Annotation Comments

Source: https://zotflow.peterduan.dev/releases/0.6.0

Apply the wrap_editable filter to annotation comments within your template to allow direct editing of comments in source notes.

```jinja2
## Annotations  

{%- for attachment in item.attachments -%}  

{%- if attachment.annotations.length > 0 -%}  

### {{ attachment.filename }}  

{%- for annotation in attachment.annotations -%}  

> [!zotflow-{{ annotation.type }}-{{ annotation.color }}] [{{ attachment.filename }}, p.{{ annotation.pageLabel }}](obsidian://zotflow?type=open-attachment&libraryID={{ attachment.libraryID }}&key={{ attachment.key }}&navigation={{ annotation.key | process_nav_info}})  

{%- if annotation.type == "ink" or annotation.type == "image"-%}  

> > ![[{{settings.annotationImageFolder}}/{{ annotation.key }}.png]]  

{%- else -%}  

> > {{ annotation.text | replace: newline, quote_string_2 }}  

{%- endif -%}  

>  

> {{ annotation.comment | wrap_editable: "ANNO", annotation.key | replace: newline, quote_string }}  

^{{ annotation.key }}  

  

{%- endfor -%}  

{%- endif -%}  

{%- endfor -%}  

{%- endif -%
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.