Emit a heading where a <details> fold was

A seed method's source was wrapped in <details>/<summary>. That fold only
opens in a renderer that passes HTML through. Everywhere else -- a Word or
PDF export, a plain Markdown viewer, a model reading the file -- the wrapper
is literal text, and the fold's label stops being a label and becomes a line
of markup.

Found by walking the generated Markdown against the Markdig converter in
mcpOffice, whose documented behaviour for an HTML block is to emit it as a
plain text paragraph. Every other construct the generator writes -- headings,
GFM pipe tables, fenced code, lists, bold, inline code -- maps to a real Word
equivalent, so this one call site was the whole distance between an extraction
and a document somebody can hand over.

The trade is honest: the fold is lost on GitHub, so a long seed body makes
that section longer to scroll. These files are read far more often than they
are scrolled.

Guarded by a fence-aware check that no sample project's Markdown, in either
language, opens a line with raw HTML outside a code fence. 348 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W45tzJFX3NoSrk7svtQeKT

Author: peopleworks

CHANGELOG.md

@@ -54,11 +54,27 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   A key is never read from or written to the configuration file: the endpoint and the model name
   are settings, a key is a secret, and that file lives in a home directory that gets copied around.
 
+- **The Markdown we generate is Markdown** ([#28]). A seed method's source was wrapped in a
+  `<details>` fold. That collapses on GitHub and nowhere else: in a Word or PDF export, in a plain
+  Markdown viewer, and to a model reading the file, the wrapper is literal text and the fold's
+  label — "Source code of PopulateStatuses" — stops being a label and becomes a line of markup. It
+  is now a heading, which survives the trip and takes its place in the document outline. The fold
+  is lost on GitHub; these files are read far more often than they are scrolled. Found by walking
+  the output against the Markdig converter in [mcpOffice], whose documented behaviour for an HTML
+  block is to emit it as plain text — every other construct we write already maps to a real Word
+  equivalent, so this one call site was the whole distance between an extraction and a document
+  somebody can hand over.
+
 ### Internal
 
-- First tests over `ProjectDiffEngine`, which is why the key above survived. 345 tests.
+- First tests over `ProjectDiffEngine`, which is why the key above survived.
+
+- Every sample project's Markdown is now checked, in both languages, for a line that opens raw HTML
+  outside a code fence. 348 tests.
 
 [#24]: https://github.com/peopleworks/XAFLogicExplainer/issues/24
+[#28]: https://github.com/peopleworks/XAFLogicExplainer/issues/28
+[mcpOffice]: https://github.com/MBrekhof/mcpOffice
 
 [#21]: https://github.com/peopleworks/XAFLogicExplainer/pull/21
 [@MBrekhof]: https://github.com/MBrekhof

README.md

@@ -330,7 +330,7 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | Pluggable publishing targets (`IDocumentationSink`) |
 | ✅ | **MCP server** — 10 tools, live against your source |
 | ✅ | **Installable Claude Code plugin** with skill and MCP server |
-| ✅ | **345 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
+| ✅ | **348 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
 | ✅ | **DevExpress ground-truth catalog**, generated locally by licensees |
 
 PeopleWorks Copilot, where this tool grew up, is now one sink among several rather than the

src/XafLogicExplainer.Core/Generators/MarkdownDocumentationGenerator.cs

@@ -840,13 +840,16 @@ private DocumentSection GenerateConfigurationSection(ExtractedProject project)
 
                 if (!string.IsNullOrEmpty(seed.RawSourceCode))
                 {
-                    sb.AppendLine("<details>");
-                    sb.AppendLine($"<summary>{_l.SourceCodeOf} {seed.MethodName}</summary>");
+                    // A heading rather than a <details> fold. The fold only opens in a renderer that
+                    // passes HTML through, and everywhere else -- a Word or PDF export, a plain
+                    // Markdown viewer, a model reading the file -- the wrapper is literal text and the
+                    // label stops being a label. This costs the fold on GitHub, which is the trade:
+                    // these files are read far more often than they are scrolled.
+                    sb.AppendLine($"#### {_l.SourceCodeOf} {seed.MethodName}");
                     sb.AppendLine();
                     sb.AppendLine("```csharp");
                     sb.AppendLine(seed.RawSourceCode);
                     sb.AppendLine("```");
-                    sb.AppendLine("</details>");
                     sb.AppendLine();
                 }
             }

tests/XafLogicExplainer.Tests/PortableMarkdownTests.cs

@@ -0,0 +1,97 @@
+using XafLogicExplainer.Core.Generators;
+using XafLogicExplainer.Core.Models;
+
+namespace XafLogicExplainer.Tests;
+
+/// <summary>
+/// That the Markdown we generate is Markdown, and not Markdown plus HTML that only a browser opens.
+/// </summary>
+/// <remarks>
+/// The seed section wrapped a method's source in a <c>&lt;details&gt;</c> fold. On GitHub that
+/// collapses; anywhere else the wrapper is literal text and the fold's label — "Source code of
+/// PopulateStatuses" — stops being a label and becomes a line of markup. "Anywhere else" is most
+/// places these files go: a Word or PDF export, a plain Markdown viewer, and a language model, for
+/// which the fold is tokens spent on something it cannot open.
+/// <para>
+/// Found by walking our output against the Markdig-based converter in
+/// <see href="https://github.com/MBrekhof/mcpOffice">mcpOffice</see>, whose documented behaviour for
+/// an HTML block is to emit it as a plain text paragraph. Every other construct we write — headings,
+/// pipe tables, fenced code, lists, bold, inline code — maps to a real Word equivalent, so this one
+/// call site was the whole difference between an extraction and a document someone can hand over.
+/// </para>
+/// </remarks>
+public class PortableMarkdownTests
+{
+    private static readonly (string Name, ExtractedProject Project)[] Samples =
+    [
+        ("Xpo", SampleProjects.Xpo),
+        ("EfCore", SampleProjects.EfCore),
+        ("LegacyEf", SampleProjects.LegacyEf),
+        ("PocoEf", SampleProjects.PocoEf),
+        ("NoOrm", SampleProjects.NoOrm),
+        ("DeepXpo", SampleProjects.DeepXpo),
+        ("AuditedXpo", SampleProjects.AuditedXpo),
+        ("Demo", SampleProjects.Demo),
+    ];
+
+    private static string Markdown(ExtractedProject project, string language) =>
+        string.Join("\n", new MarkdownDocumentationGenerator(language)
+            .GenerateSections(project)
+            .Select(section => section.Content))
+            .Replace("\r", "");
+
+    /// <summary>
+    /// Lines that begin a CommonMark HTML block: outside a fence, a line whose first character is
+    /// <c>&lt;</c>. Inside a fence the same line is source code and is left alone, which is why this
+    /// tracks the fence rather than matching the whole document at once.
+    /// </summary>
+    private static List<string> RawHtmlLines(string markdown)
+    {
+        var offenders = new List<string>();
+        var insideFence = false;
+
+        foreach (var line in markdown.Split('\n'))
+        {
+            if (line.TrimStart().StartsWith("```", StringComparison.Ordinal))
+            {
+                insideFence = !insideFence;
+                continue;
+            }
+
+            if (!insideFence && line.TrimStart().StartsWith('<'))
+                offenders.Add(line.Trim());
+        }
+
+        return offenders;
+    }
+
+    [Theory]
+    [InlineData("en")]
+    [InlineData("es")]
+    public void NoGeneratedPageOpensALineWithRawHtml(string language)
+    {
+        foreach (var (name, project) in Samples)
+        {
+            var offenders = RawHtmlLines(Markdown(project, language));
+
+            Assert.True(offenders.Count == 0,
+                $"{name} ({language}) emits raw HTML outside a code fence, which renders as literal "
+                + $"text everywhere but a browser: {string.Join(" | ", offenders)}");
+        }
+    }
+
+    [Fact]
+    public void TheSeedSourceIsIntroducedByAHeadingRatherThanAFold()
+    {
+        // A heading survives the trip and keeps its place in the document outline; the fold did
+        // neither. The fixture that carries this is the XPO sample, whose updater has a body.
+        var english = Markdown(SampleProjects.Xpo, "en");
+
+        Assert.Contains("#### Source code of ", english, StringComparison.Ordinal);
+        Assert.Contains("#### Codigo fuente de ", Markdown(SampleProjects.Xpo, "es"), StringComparison.Ordinal);
+
+        // The label is what was lost: inside <summary> it was markup, and the reader met angle
+        // brackets where a title belonged.
+        Assert.DoesNotContain("<summary>", english, StringComparison.Ordinal);
+    }
+}