AddFrontmatter deletes every YAML comment in the existing header and rewrites its formatting, even when it only adds a new key

[matt-edmondson]

What's wrong

When a document already has frontmatter, AddFrontmatter parses it into a Dictionary<string, object>, adds the new keys, and serializes the whole dictionary again through ReplaceFrontmatter. Anything in the header that isn't a key/value pair is lost: comments disappear and the original formatting is rewritten, even though the caller only asked to add a property.

Repro

string doc = "---\n# Draft: do not publish until legal signs off\ntitle: Launch # working title\ntags: [a, b]\n---\nBody\n";
Console.Write(Frontmatter.AddFrontmatter(doc, new() { ["author"] = "Jane" }));

Observed:

---
title: Launch
tags:
- a
- b
author: Jane
---
Body

• The whole-line comment is gone.
• The inline # working title comment is gone.
• The flow list [a, b] has been turned into a block list.

Why it matters

Stamping a property such as a date, author or id onto many files is the main batch use of AddFrontmatter. Running it over a content repository silently removes editorial notes and commented-out settings from every file, and produces a large, noisy diff.

Suggested fix / acceptance criteria

• When none of the new keys already exist and there is a single block, keep the existing block text exactly as written and insert the serialized new keys before the closing delimiter.
• Only rebuild the header from the dictionary when it genuinely has to be rewritten, for example to fold stacked blocks (AddFrontmatter deletes every frontmatter block after the first #138 / PR Keep every frontmatter block when adding or combining properties [patch] #166).
• Test: for the repro, the output keeps both comments and tags: [a, b] unchanged, and adds author: Jane.

[matt-edmondson]

Triage

• Category: Bug (silent content loss)
• Priority: Medium. It hits the main batch use of AddFrontmatter, stamping a key onto many files, and silently removes YAML comments while reformatting flow collections. Nothing is corrupted beyond the header, and the loss shows up in a diff.
• Area / suggested assignment: AddFrontmatter / ReplaceFrontmatter in Frontmatter/Frontmatter.cs. Add a text-preserving fast path for a single block with only new keys.
• Duplicates: none. It is related to ExtractFrontmatter returns only the first of stacked frontmatter blocks, while ExtractBody and RemoveFrontmatter strip all of them, so later blocks' properties are lost to readers #169 (same stacked-block folding path) and to AddFrontmatter deletes every frontmatter block after the first #138 / PR Keep every frontmatter block when adding or combining properties [patch] #166. Fixing both in one PR would keep the header-handling rules consistent.
• In progress: no matching open PR.

---

Generated by Claude Code