Preserve leading XML declarations when creating frontmatter

[DandyLyons]

Summary

Make frontmatter creation aware of a leading XML declaration so md-utils never inserts an HTML-comment frontmatter block before the declaration.

XML documents may begin with a declaration such as:

<?xml version="1.0" encoding="UTF-8"?>

When that declaration is present, placing a comment before it can make the document invalid because the declaration is required to occur at the beginning of the document. md-utils should preserve the declaration and create frontmatter immediately after it.

Proposed behavior

• Detect a valid XML declaration at the legal beginning of files that use the HTML-comment frontmatter representation and may contain XML, including XML, XHTML, and SVG.
• Account for the existing optional UTF-8 BOM behavior.
• When creating frontmatter, insert the new block after the complete XML declaration instead of before it.
• Preserve the declaration, surrounding source, and original line endings byte-for-byte.
• Continue mutating an existing recognized frontmatter block in place.
• Keep placement and source rewriting entirely inside md-utils so consumers only get and set the decoded frontmatter mapping.
• Produce a deterministic diagnostic and leave the file unchanged when an apparent leading declaration is malformed and safe placement cannot be established.

If it is simpler and safe, detection may be content-based for every file using the HTML-comment representation rather than restricted by extension.

Representative result

<?xml version="1.0" encoding="UTF-8"?>
<!--
---
title: Example
---
-->
<root />

Acceptance criteria

• Creating frontmatter in an XML file with a declaration preserves the declaration as the document prolog and inserts the block after it.
• XML without a declaration retains the existing canonical creation behavior.
• UTF-8 BOM behavior remains correct.
• Existing frontmatter mutation remains source-preserving and revision-checked.
• Tests cover XML, XHTML, and SVG examples, plus malformed declaration behavior.
• Documentation describes XML-declaration-aware placement.

Related work

• Add delimiter-wrapped frontmatter support for non-Markdown files #98
• Add per-line hash-comment frontmatter #129