[Repo Assist] fix: Markdown.ToMd preserves YAML frontmatter (#1165)

* fix: Markdown.ToMd preserves YAML frontmatter

When Markdown.ToMd serialises a parsed MarkdownDocument back to Markdown
text, YamlFrontmatter paragraphs were silently dropped. Documents
containing a YAML front-matter block (--- ... ---) would lose that block
on round-trip.

Fix: emit the --- delimiters and frontmatter lines in formatParagraph so
round-trips are lossless.

Add two new tests: one with populated frontmatter and one with an empty
block.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: trigger checks

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Don Syme <dsyme@users.noreply.github.com>

Author: 3 people

RELEASE_NOTES.md

@@ -9,6 +9,7 @@
 * Bump `System.Memory` transitive-dependency pin from 4.5.5 to 4.6.3.0
 
 ### Fixed
+* Fix `Markdown.ToMd` silently dropping YAML frontmatter when serialising a parsed `MarkdownDocument` back to Markdown text. Frontmatter is now preserved with its `---` delimiters.
 * Fix `Markdown.ToMd` converting tight lists (no blank lines between items) into loose lists by emitting a blank line after every item. Tight lists now round-trip correctly without inter-item blank lines.
 * Fix `Markdown.ToMd` serialising `HardLineBreak` as a bare newline instead of two trailing spaces + newline. The correct CommonMark representation `"  \n"` is now emitted, so hard line breaks survive a round-trip through `ToMd`.
 * Fix `Markdown.ToMd` serialising `HorizontalRule` as 23 hyphens regardless of the character used in the source. It now emits exactly three characters matching the parsed character (`---`, `***`, or `___`), giving faithful round-trips.

src/FSharp.Formatting.Markdown/MarkdownUtils.fs

@@ -298,7 +298,14 @@ module internal MarkdownUtils =
           | InlineHtmlBlock(code, _, _) ->
               let lines = code.Replace("\r\n", "\n").Split('\n') |> Array.toList
               yield! lines
-          | YamlFrontmatter _ -> ()
+          | YamlFrontmatter(lines, _) ->
+              yield "---"
+
+              for line in lines do
+                  yield line
+
+              yield "---"
+              yield ""
           | Span(body = body) -> yield formatSpans ctx body
           | QuotedBlock(paragraphs = paragraphs) ->
               for paragraph in paragraphs do

tests/FSharp.Markdown.Tests/Markdown.fs

@@ -1632,6 +1632,22 @@ let ``ToMd preserves a link with a title`` () =
     result |> should contain "[FSharp]("
     result |> should contain "https://fsharp.org"
 
+[<Test>]
+let ``ToMd preserves YAML frontmatter`` () =
+    let input = "---\ntitle: My Page\ndate: 2024-01-01\n---\n\nHello world.\n"
+    let result = input |> toMd
+    result |> should contain "---"
+    result |> should contain "title: My Page"
+    result |> should contain "date: 2024-01-01"
+    result |> should contain "Hello world."
+
+[<Test>]
+let ``ToMd preserves empty YAML frontmatter`` () =
+    let input = "---\n---\n\nHello.\n"
+    let result = input |> toMd
+    result |> should contain "---"
+    result |> should contain "Hello."
+
 [<Test>]
 let ``ToMd serialises EmbedParagraphs by delegating to Render()`` () =
     // EmbedParagraphs was previously falling through to the catch-all '| _' branch,