Fix mkdocs-macros Jinja2 syntax errors in generated block docs#2012
Open
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".
| (Jinja2) parse errors like "unexpected char '$'". | ||
| """ | ||
|
|
||
| import pytest |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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{{ }}).