From 2bc7419f3bfca8410d4f123022d5a45717fd8c61 Mon Sep 17 00:00:00 2001
From: Guilherme Moreira Rodrigues <gui.rodrigues@lerian.studio>
Date: Tue, 20 Oct 2026 15:30:11 -0300
Subject: [PATCH] fix(helm-upgrade-doc): wrap generated guides in a hidden
 Liquid raw block

charts.lerian.studio is built by GitHub Pages (Jekyll 3.10), which runs Liquid
over every .md. Upgrade guides carry Helm template snippets ({{ ... }}): they
raised hundreds of Liquid warnings and an unterminated one broke the whole
site build (LerianStudio/helm#2565 fixes the existing guides).

Generated guides that contain {{ or {% are now wrapped in
<!-- {% raw %} --> ... <!-- {% endraw %} -->: Liquid honours the tags and
GitHub's markdown view hides the comments. Raw markers are stripped from the
few-shot examples and from the model output first, so the model never echoes
them and the wrap is never nested (nested raw breaks Liquid too).
---
 .../helm-upgrade-doc/scripts/generate-doc.sh   | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/docs/helm-upgrade-doc/scripts/generate-doc.sh b/src/docs/helm-upgrade-doc/scripts/generate-doc.sh
index 24b37121..43507318 100755
--- a/src/docs/helm-upgrade-doc/scripts/generate-doc.sh
+++ b/src/docs/helm-upgrade-doc/scripts/generate-doc.sh
@@ -28,13 +28,24 @@ CHART_DIFF=$(git diff "${PREV_TAG}".."${CURRENT_TAG}" -- "${CHART_PATH}/Chart.ya
 VALUES_DIFF=$(git diff "${PREV_TAG}".."${CURRENT_TAG}" -- "${CHART_PATH}/values.yaml" 2>/dev/null | head -400 || true)
 TEMPLATE_DIFF=$(git diff "${PREV_TAG}".."${CURRENT_TAG}" -- "${CHART_PATH}/templates/" 2>/dev/null | head -300 || true)
 
+# Liquid guard: charts.lerian.studio is built by GitHub Pages (Jekyll 3.10), which runs
+# Liquid over every .md, so Helm template snippets ({{ ... }}) in a guide warn or, when
+# malformed, break the whole site build. Generated guides are wrapped in a raw block
+# hidden in HTML comments (Liquid honours it, GitHub's markdown view hides it). Markers
+# are stripped from examples and model output first: a nested raw breaks Liquid too.
+strip_liquid_raw() {
+  { grep -vE '^[[:space:]]*<!--[[:space:]]*\{%-?[[:space:]]*(end)?raw[[:space:]]*-?%\}[[:space:]]*-->[[:space:]]*$' || true; } \
+    | sed -E 's/\{%-?[[:space:]]*(end)?raw[[:space:]]*-?%\}//g'
+}
+
 # Load 2 most recent existing UPGRADE docs as few-shot examples
 EXAMPLES=""
 if [ -d "$DOCS_PATH" ]; then
   # shellcheck disable=SC2012
   while IFS= read -r doc_file; do
     DOC_NAME=$(basename "$doc_file")
-    DOC_CONTENT=$(cat "$doc_file")
+    # Drop the Liquid raw markers (see "Liquid guard" above) so the model never copies them.
+    DOC_CONTENT=$(strip_liquid_raw < "$doc_file")
     EXAMPLES="$(printf '%s\n=== %s ===\n%s\n' "$EXAMPLES" "$DOC_NAME" "$DOC_CONTENT")"
   done < <(ls -t "${DOCS_PATH}"/UPGRADE-*.md 2>/dev/null | head -2)
 fi
@@ -168,6 +179,11 @@ if echo "$FIRST_LINE" | grep -q '^```'; then
   CONTENT=$(echo "$CONTENT" | sed '1d; $d')
 fi
 
+CONTENT=$(printf '%s\n' "$CONTENT" | strip_liquid_raw)
+if printf '%s' "$CONTENT" | grep -qE '\{\{|\{%'; then
+  CONTENT=$(printf '<!-- {%% raw %%} -->\n%s\n<!-- {%% endraw %%} -->' "$CONTENT")
+fi
+
 mkdir -p "$DOCS_PATH"
 printf '%s\n' "$CONTENT" > "$DOC_FILE"