Summary
The docs build (cipherstash/docs) broke on eql-3.0.0-alpha.3 because the generated API.md contains an unbalanced <tt> tag:
./content/stack/reference/eql/index.mdx
2153: Expected a closing tag for `<tt>` before the end of `paragraph`
Turbopack build failed
Root cause
In src/v3/jsonb/operators.sql, the jsonb selector operator's @warning documents a cast:
--! parameter (`$1`, the Proxy interface) or an explicit cast (`col -> 'sel'::text`).
--! A bare untyped literal (`col -> 'sel'`) resolves to the NATIVE `jsonb -> text`
Doxygen auto-links the bare word text (it collides with a documented symbol) into a cross-reference — even inside inline code. The XML becomes:
<computeroutput>col -> 'sel'<ref refid="lints_8sql_...">text</ref></computeroutput>
i.e. a <ref> link nested inside <computeroutput>. When rendered to Markdown that surfaces as an unbalanced <tt>, and the :: is swallowed (the cast reads 'sel'text). MDX requires every tag to be balanced, so the whole docs deploy fails.
This is version-sensitive: doxygen 1.15.0 masks it, but the CI toolchain emits the broken <tt>. The trigger — the nested <ref> — is present regardless of version.
Fix
PR #: prefix the two text occurrences with Doxygen's % no-autolink marker (::%text, -> %text). Verified locally: the nested <ref> disappears and col -> 'sel'::text renders as clean, balanced inline code (the :: is preserved too).
Alternatives considered
AUTOLINK_SUPPORT = NO in the Doxyfile — a global root fix (the Markdown converter already flattens <ref> to plain text, so Markdown impact is minimal), but it removes cross-links from the HTML docs too. A bigger call for maintainers.- Converter guard (
tasks/docs/generate/xml-to-markdown.py) to never emit a link inside inline code — more general but heavier.
Downstream mitigation
cipherstash/docs#52 makes the docs generator defensively strip <tt> so a malformed upstream doc can't take the build down again. That's a safety net; this issue is the actual source bug.
Summary
The docs build (cipherstash/docs) broke on eql-3.0.0-alpha.3 because the generated
API.mdcontains an unbalanced<tt>tag:Root cause
In
src/v3/jsonb/operators.sql, the jsonb selector operator's@warningdocuments a cast:Doxygen auto-links the bare word
text(it collides with a documented symbol) into a cross-reference — even inside inline code. The XML becomes:i.e. a
<ref>link nested inside<computeroutput>. When rendered to Markdown that surfaces as an unbalanced<tt>, and the::is swallowed (the cast reads'sel'text). MDX requires every tag to be balanced, so the whole docs deploy fails.This is version-sensitive: doxygen 1.15.0 masks it, but the CI toolchain emits the broken
<tt>. The trigger — the nested<ref>— is present regardless of version.Fix
PR #: prefix the two
textoccurrences with Doxygen's%no-autolink marker (::%text,-> %text). Verified locally: the nested<ref>disappears andcol -> 'sel'::textrenders as clean, balanced inline code (the::is preserved too).Alternatives considered
AUTOLINK_SUPPORT = NOin the Doxyfile — a global root fix (the Markdown converter already flattens<ref>to plain text, so Markdown impact is minimal), but it removes cross-links from the HTML docs too. A bigger call for maintainers.tasks/docs/generate/xml-to-markdown.py) to never emit a link inside inline code — more general but heavier.Downstream mitigation
cipherstash/docs#52 makes the docs generator defensively strip
<tt>so a malformed upstream doc can't take the build down again. That's a safety net; this issue is the actual source bug.