Summary

Fixes #590.

Markdoc.format was emitting text nodes verbatim, so a text node whose content happened to be [a](url) (produced by parsing \[a](url)) was written back as [a](url) — which the parser re-reads as a link. The original escaping was silently dropped on every format round-trip.

Root Cause

In formatter.ts, the 'text' case of formatNode (previously line 214) passed content directly to escapeMarkdownCharacters. That helper only re-escaped characters that could form headings, blockquotes, or emphasis — it had no knowledge of inline-link or autolink syntax.

Three patterns broke:

Solution

Three targeted guards are applied to content before the existing per-character escaping:

1. startsWithLink(content, offset) — a small scanner that follows CommonMark's balanced-parenthesis rule for link destinations. It escapes [ only when it genuinely opens an inline link [text](url). Patterns such as ![Image](url_with_unbalanced_parens) — which the parser already treats as plain text — are left untouched.

2. /<scheme:\/\/...>/ regex — escapes < that would be re-parsed as a scheme-based autolink (e.g. <https://example.com>).

3. nextSibling tracking — formatChildren now forwards the next sibling into each child's options. When a text node ends with ! and its next sibling is a link node (the AST shape produced by \![link](url)), the trailing ! is escaped to \!, preventing the sequence from being re-read as an image.

Testing

• Added 'preserves escaping on links, images, and autolinks (issue #590)' in src/formatter.test.ts:
  • \[a](url) round-trips stably (formatter re-emits \[)
  • \<https://example.com> round-trips stably (formatter re-emits \<)
  • [brackets] (no URL) gains no spurious backslash
  • <not-an-autolink> gains no spurious backslash
  • \!\[a](url) re-parses to the same text-node content (![a](url))
• All 260 existing specs still pass.
• Run with: npm test

Checklist

• Fixes the root cause (not just the symptom)
• New tests cover the exact scenarios from issue Escaped links/images lose escaping after formatting #590
• All existing tests pass (260 specs, 0 failures)
• No unrelated changes
• Code style matches project conventions
• Lint clean (npm run lint — no errors)