Why parse-and-stringify rewrites your Obsidian notes, and how specgit keeps the bytes you didn't touch

specgit — Mon, 26 Oct 2026 18:13:10 +0000

By the specgit team

Most of us have written this pipeline at least once. You parse a Markdown file into a syntax tree with remark, change one node, and stringify the tree back to text. For a .canvas file the move is even shorter: JSON.parse, mutate one object, JSON.stringify. Then someone points it at a real Obsidian vault in GitHub, and the first pull request arrives as a wall of red and green.

The reason is that a syntax tree records what a document means, not how it was typed. One document can be written many ways: a bullet can start with -, * or +, and emphasis can use asterisks or underscores. Once the parser has thrown those choices away, the stringifier has to make them again, and it makes them its own way on every save. Obsidian raises the stakes, because a vault is full of syntax a general Markdown tool has never heard of: callouts, wikilinks, block references, custom task statuses like [/], Dataview fields and Templater tags. A writer that doesn't know [[Note]] is a link plays it safe by escaping the brackets, which is precisely what breaks the link inside Obsidian.

We ran a note from our test vault through a standard Markdown writer after changing "weekly" to "daily" in one list item. Git showed eleven lines added and nine removed. The callout header became plain text, every wikilink was escaped, the tab-indented sublist came back as spaces and asterisks, and the "in progress" task stopped being a task. The board fared no better through a generic JSON writer, which deleted everything but the opening and closing braces and wrote the file back as 269 lines, so one moved card cost 301 changed lines.

specgit works with Obsidian vaults by refusing to regenerate what it didn't change. When you save, every block you didn't touch is written back with its original bytes, and only the edited block goes through the writer (inside a list, only the edited item). This is the same one-word edit as specgit saves it:

 > Ship the editor to **three pilot teams** by ==Nov 15==. See [[Launch/Risks#Top risks|top risks]] and the [[Launch/Timeline]].

 ## Goals ^goals
-1. Three pilot teams editing weekly
+1. Three pilot teams editing daily
 2. Zero data-loss reports
    - Measured by support tickets
    - And by [[Launch/Metrics#^retention|retention]]

The hard part is proving each splice safe. Before anything is saved, specgit reads its own output back and checks that it means exactly what the editor shows, and if an edit would change how a neighboring block reads, it rewrites that neighbor too. Constructs the editor can't represent, such as bold nested inside bold, stay raw, and line endings, a byte order mark and the file's ending count as part of the file. Canvas boards get the same discipline, so moving one card changes that card's line and nothing else.

All of this is held in place by 140 test files, six checks on every one of them, every CommonMark and GitHub spec example, and a harness that asks the real Obsidian app how it reads each saved note.

The full post has the three-file Canvas diff before and after, how the save works, and the whole test setup: specgit.com/blog/obsidian-fidelity.

DEV Community: specgit

Why parse-and-stringify rewrites your Obsidian notes, and how specgit keeps the bytes you didn't touch