Fix critic.mdx rendering issue caused by embedded triple backticks

[xingyaoww]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

Fixes the rendering issue on https://docs.openhands.dev/sdk/guides/critic where the page displayed repeated content like:

Hello world! This is a well-known test file.
It has 5 lines, including empty ones. Numbers like 42 and 3.14 don't count as words.

Root Cause

The Python example file (34_critic_example.py) contains triple backticks inside a multi-line string (used to show example file content in the task prompt). When the sync script copied this content into the MDX documentation, these embedded backticks closed the markdown code block prematurely, causing:

• The content after the first embedded ``` to render as regular markdown
• Repeated content appearing multiple times on the page
• Broken page structure

Changes

1. .github/scripts/sync_code_blocks.py: Added escape_embedded_backticks() function that inserts zero-width spaces between backticks ( ​​ `) to prevent markdown parsing issues while preserving visual appearance

2. sdk/guides/critic.mdx: Regenerated with properly escaped content

3. Bonus: Also synced a few other documentation files with latest agent-sdk examples

Verification

Ran local Mintlify dev server and confirmed the critic page now renders correctly:

• Python code block displays properly with 244 lines
• "See all 244 lines" expandable button works
• "Running the Example" and "Example Output" sections properly formatted
• No more repeated content

[xingyaoww]

Local Verification Screenshot

Here's a screenshot from the local Mintlify dev server confirming the page now renders correctly:

Key improvements visible:

• ✅ "Ready-to-run Example" section displays properly
• ✅ Python code block shows with "See all 244 lines" expandable button
• ✅ "Running the Example" bash command section renders correctly
• ✅ "Example Output" section shows expected output
• ✅ No more repeated "Hello world!" content appearing

The fix escapes embedded triple backticks in the Python source file using zero-width spaces, preventing the markdown parser from incorrectly treating them as code block delimiters.

[xingyaoww]

Local Verification Screenshot

Here's a screenshot from the local Mintlify dev server confirming the page renders correctly after the fix:

Click to see screenshot

The screenshot shows:

• Ready-to-run Example section with properly rendered Note component
• Python code block with examples/01_standalone_sdk/34_critic_example.py filename
• "See all 244 lines" expandable button (confirming full code is present)
• Running the Example bash command block
• Example Output section with expected output

Key fixes verified:

• ✅ Python code block displays properly with 244 lines
• ✅ "See all 244 lines" expandable button works
• ✅ "Running the Example" and "Example Output" sections render correctly
• ✅ No more repeated "Hello world!" content appearing on the page

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Pragmatic fix for a real problem, but the zero-width space hack has implications that need consideration.

Summary: The fix addresses the immediate rendering issue, but introduces invisible characters that could cause copy-paste problems for users. Consider the alternative approach suggested below.

[xingyaoww]

@OpenHands can you fix the unresolved comments: #368 (review)

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

I've successfully addressed all 4 unresolved review comments on PR #368. The changes have already been pushed to the fix/critic-mdx-embedded-backticks branch in commit f578e1b.

Checklist of Review Comments Addressed

• Zero-width spaces tradeoff (PRRT_kwDOPqI_Z85xybEI): Added comprehensive docstring explaining the tradeoff, justification, and idempotency guarantee
• Regex fragility (PRRT_kwDOPqI_Z85xybEO): Fixed pattern with \n? to handle code blocks without trailing newlines + added test case
• Comparison logic complexity (PRRT_kwDOPqI_Z85xybER): Simplified to use old_display/new_display variable names with clearer logic
• Missing tests (PRRT_kwDOPqI_Z85xybEW): Created tests/test_sync_code_blocks.py with 17 passing tests covering all requested cases

Files Changed

1. .github/scripts/sync_code_blocks.py - Improved docstrings, regex patterns, comparison logic, and empty content handling
2. tests/test_sync_code_blocks.py - New test file with comprehensive coverage

Actions Completed

• ✅ Committed and pushed changes to remote branch
• ✅ Replied to all 4 review threads explaining how feedback was addressed
• ✅ Resolved all review threads (verified all 5 threads now show isResolved: true)

The changes are concise and directly address the reviewer's feedback without any extraneous modifications.