Skip to content

Commit f150749

Browse files
committed
fix(docs-gen): escape {{ in generated API markdown prose
docfx preserves verbatim spec-marker text from XML doc comments like "{{term(data set)}} of the number of {{termplural(Asset)}} ..." in the generated `*.md` files. VitePress's underlying Vue template compiler then treats `{{ ... }}` as a mustache interpolation and tries to parse the contents as a JavaScript expression. Spec markers contain unquoted spaces and operator-like tokens, so the parse fails and the Docs-site CI's Build VitePress site job aborts with errors like `Error parsing JavaScript expression: Unexpected token`. Extend the post-processing awk pass to rewrite every `{{` outside fenced code blocks as `{{`. The html-entity form survives the markdown -> HTML pipeline and presents the original characters to readers without engaging Vue's mustache parser. Standalone `}}` is harmless once its opening `{{` is gone, so it is left alone.
1 parent dcc4cdb commit f150749

1 file changed

Lines changed: 11 additions & 2 deletions

File tree

docs/scripts/generate-api-ref.sh

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -182,13 +182,22 @@ while IFS= read -r -d '' md_file; do
182182
/^```/ { in_fence = !in_fence; print; next }
183183
in_fence { print; next }
184184
{
185-
# Replace `<X` (uppercase) with `&lt;X` by walking each match.
185+
# Replace `<X` (uppercase) or `<[` with `&lt;X` / `&lt;[` by
186+
# walking each match.
186187
out = ""; s = $0
187188
while (match(s, /<([A-Z]|\[)/)) {
188189
out = out substr(s, 1, RSTART - 1) "&lt;" substr(s, RSTART + 1, RLENGTH - 1)
189190
s = substr(s, RSTART + RLENGTH)
190191
}
191-
print out s
192+
line = out s
193+
# Replace `{{` with `&#123;&#123;` so Vue does not treat the
194+
# token as a mustache interpolation. docfx preserves verbatim
195+
# spec-marker text like `{{term(data set)}}` from XML doc
196+
# comments, which Vue would otherwise try to parse as the
197+
# JavaScript expression `term(data set)` and reject. The
198+
# html-entity form survives the markdown -> HTML pipeline.
199+
gsub(/\{\{/, "\\&#123;\\&#123;", line)
200+
print line
192201
}
193202
' "${md_file}" > "${md_file}.tmp" && mv "${md_file}.tmp" "${md_file}"
194203
done < <(find docs/api -name '*.md' -not -name 'index.md' -print0)

0 commit comments

Comments
 (0)