Fix mkdocs-macros Jinja2 syntax errors in generated block docs#2012
Fix mkdocs-macros Jinja2 syntax errors in generated block docs#2012
Conversation
The mkdocs-macros plugin processes all Markdown files through Jinja2
before rendering. Block source files contain `{{ $parameters.xxx }}`
patterns in LONG_DESCRIPTION strings and Field descriptions that flow
into the generated docs verbatim. Jinja2 chokes on the `$` inside
`{{ }}` expressions with "unexpected char '$'" errors.
Add a post-processing step in build_block_docs.py that escapes any
`{{ ... }}` expression containing `$` in the final page content before
writing to disk. Also add a Jinja2 syntax validation script and CI step
in the docs workflow, plus unit tests for the escaping logic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
yeldarby
requested review from
PawelPeczek-Roboflow,
grzegorz-roboflow,
hansent and
probicheaux
as code owners
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b126068b5e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # This catches patterns like {{ $parameters.xxx }} in LONG_DESCRIPTION strings, | ||
| # Field descriptions, and other generated content that would cause mkdocs-macros | ||
| # Jinja2 parse errors ("unexpected char '$'"). | ||
| JINJA2_DOLLAR_EXPRESSION_PATTERN = re.compile(r"(\{\{(?:(?!\}\}).)*?\$(?:(?!\}\}).)*?\}\})") |
There was a problem hiding this comment.
The new JINJA2_DOLLAR_EXPRESSION_PATTERN only uses . inside tempered groups, so it does not match across newlines; inputs like {{\n$parameters.foo\n}} (or any placeholder split over multiple lines in generated descriptions/examples) are left unescaped and will still trigger mkdocs-macros parse failures (unexpected char '$'). This means the fix is incomplete for multiline docs content and the CI validation step can still fail on those generated pages.
Useful? React with 👍 / 👎.
1 participant
Summary
Fixes Jinja2 parse errors (
unexpected char '$') that occur when mkdocs-macros processes generated documentation containing{{ $parameters.xxx }}expressions.Changes
build_block_docs.py: Added_escape_jinja2_expressions()helper that escapes any{{ ... }}blocks containing$signs using Jinja2 literal syntax ({{ '{{' }}). Applied to both block family pages and kind pages during generation.validate_docs_jinja2.py: New validation script that parses all.mdfiles underdocs/as Jinja2 templates and reports any syntax errors. Acts as a safety net for future regressions.docs.yml: Added a CI step to run the Jinja2 validation script after doc generation, before deployment.tests/docs/test_build_block_docs.py: Unit tests covering the escaping logic, including real-world cases (email notification descriptions, field descriptions with multiple parameter references) and edge cases (already-escaped expressions, CSS braces, bare$outside{{ }}).