ZotFlow 1.4.0

This release is about one thing: what happens to your writing when a note travels between Obsidian and Zotero. Callouts, embeds, tags and footnotes now come back the way you wrote them, tables stop breaking, and a class of silent damage to notes containing code examples is gone.

Updating is safe. You will see a small one-time difference in notes that use task lists or embeds — described at the bottom — and nothing after that.

Highlights

• Callouts survive — > [!note], titles, folding and nesting all round-trip intact instead of coming back as > \[!note].
• Embeds survive — ![[Note]], ![[image.png|400]] and PDF page links stay embeds instead of being flattened into plain image links.
• Tags at the start of a line survive — a line beginning with #project is a tag again, not \#project.
• Inline footnotes survive — including ones that wrap onto a second line.
• Notes containing code examples are no longer damaged. This was the serious one; see below.
• Tables stop breaking when a cell contains a wiki link with an alias, a Zotero citation, or a highlight.
• Repeated syncing no longer accumulates changes in your notes.
• A new documentation page states exactly which syntax is supported, so you no longer have to find out by losing something.

Notes containing code examples are no longer damaged

If a note contained a code block with Markdown examples inside it — a [[wikilink]], a - [x] task, a [^1] footnote, an ![[embed]] — those examples were being rewritten, and the damage was written back to Zotero. It could not be undone by syncing again.

Anything inside a code block or inline code is now left completely alone.

Worth a look

If you keep notes that document Markdown — how-to notes, plugin snippets, teaching material — it is worth opening them and checking the code blocks. Any damage already written to Zotero is still there; this release stops it happening again but cannot repair what was lost.

Tables stop breaking

A table cell containing certain things used to tear the row apart, dropping whatever came after it:

In a cell	What happened
[[Note|alias]]	The row split at the alias bar and the link was cut in half
A Zotero citation or highlight	Same, if the visible text contained a bar
An annotation with a line break	The row split into two rows

Worse, the damage went back to Zotero and the row changed again on every sync. All of these are fixed.

Repeated syncing no longer accumulates changes

A Zotero citation inside a bullet list or a table gained an extra invisible wrapper every single time the note synced. Nothing was visibly wrong at first, but the note grew, and the growth had no limit.

Notes now settle: after the one-time formatting described below, a note you do not edit stays byte-for-byte identical no matter how many times it syncs.

Know exactly what is supported

A new page — Markdown Syntax Support — lists every construct in three groups:

• what comes back exactly as you wrote it;
• what is reformatted but means the same thing (bullet markers, table padding and so on — worth knowing so a one-time diff does not look like a bug);
• the five things that are not supported, each with what to write instead.

The short version of that last group: code block language tags (so a mermaid diagram stops rendering), YAML frontmatter, the Tasks plugin's custom checkbox statuses, unused link definitions, and a vertical bar inside maths inside a table. Where a workaround exists it is usually a persist region, which keeps the content next to the item and never sends it to Zotero.

Bug fixes

• Underlined text no longer loses nested links — <u> around a link kept the words and dropped the URL.
• Notes created by older ZotFlow versions display correctly — an internal marker line could show up as editable body text.
• <u>, <sub> and <sup> keep their inner formatting instead of being flattened to plain text.
• Wiki links with punctuation in the target work — [[Q&A notes]], [[snake_case_note]], [[a~b]] and non-Latin titles all round-trip. (An asterisk in the target still does not; see the syntax page.)
• Emoji, right-to-left text and rare characters are preserved exactly, including multi-part emoji such as 👨‍👩‍👧‍👦.

Changes you will see once

Two things look different the first time an existing note syncs, then stay put:

• Task lists are written the way Zotero's own editor writes them. The Markdown is identical in both directions; only the underlying note changes shape, so already-synced task lists show a one-time difference.
• Embeds are now kept as ![[...]]. Notes already synced with the old flattened ![](...) form stay as they are — only new conversions keep the embed.