DOC-6939 Stop publishing HTML-commented content to the AI outputs

layouts/partials/process-markdown-content.html

@@ -16,6 +16,30 @@
 {{- $content := .RawContent -}}
 {{- $visited := .Visited | default (slice) -}}
 
+{{- /* Drop HTML-comment blocks before anything else looks at the content.
+
+       Hugo is configured with unsafe = true, so a comment passes through to the rendered
+       HTML and is invisible to readers -- which is how authors park prose that should not
+       be published yet. Nothing downstream of here knew that, so the commented text was
+       reaching the JSON feed as real section content and the Markdown output as real body
+       text: we were publishing to AI consumers exactly what we withhold from readers. On
+       develop/clients/observability that was a whole "Tracing overview" section, kept
+       because the explanation is good but the clients do not support tracing yet.
+
+       The open delimiter must be at the start of a line. That is what separates an author's
+       block comment from a comment inside a code example -- a Maven snippet carries
+       "</version> <!-- Check for the latest version -->" mid-line, and stripping that would
+       damage the sample. Measured over the whole corpus, the line-anchored form removes 48
+       comments totalling about 19,200 characters and never matches inside a fenced code
+       block, where the unanchored form would have hit 9. The residual is inline comments,
+       which are small and usually part of a code sample anyway.
+
+       Known limit: a block comment written at column 0 *inside* a fenced code block would
+       still be stripped. None exists today. Both the literal and entity-escaped forms are
+       matched, because RawContent arrives escaped in some contexts. */ -}}
+{{- $content = $content | replaceRE "(?ms)^<!--.*?-->" "" -}}
+{{- $content = $content | replaceRE "(?ms)^&lt;!--.*?--&gt;" "" -}}
+
 {{- /* Expand embed-md shortcodes before other transforms so embedded content can be processed too. */ -}}
 {{- $content = partial "markdown-embed-md.html" (dict "RawContent" $content "Page" .Page "Visited" $visited) -}}
 {{- /* Split wide table-scrollable blocks for AI-facing Markdown output only. */ -}}

layouts/partials/toc-from-markdown.html

@@ -25,6 +25,15 @@
        what counts as code and their ids stay in step. */ -}}
 {{- $content = $content | replaceRE "(?s)```.*?```" "" -}}
 
+{{- /* Drop HTML-comment blocks too, so prose an author has parked does not appear in the
+       navigation. develop/clients/observability comments out a whole "Tracing overview"
+       section, which was published here as a real entry pointing at an anchor that does
+       not exist on the page, because Hugo renders no heading for commented-out text.
+       Line-anchored open delimiter, matching process-markdown-content.html -- change the
+       two together. Safe to run after the code strip above, which has already removed any
+       comment living inside a code sample. */ -}}
+{{- $content = $content | replaceRE "(?ms)^<!--.*?-->" "" -}}
+
 {{- /* Find all ## and ### headers in the raw markdown */ -}}
 {{- /* Pattern matches lines starting with ## or ### followed by space and title */ -}}
 {{- $headerPattern := `(?m)^(#{2,3}) +(.+)$` -}}