Skip to content

fix: escape bare < in generated MDX to fix Vercel doc builds#1478

Merged
SumanthRH merged 1 commit intomainfrom
fix/docs-mdx-escape-bare-angle-brackets
Apr 8, 2026
Merged

fix: escape bare < in generated MDX to fix Vercel doc builds#1478
SumanthRH merged 1 commit intomainfrom
fix/docs-mdx-escape-bare-angle-brackets

Conversation

@tyler-griggs
Copy link
Copy Markdown
Member

@tyler-griggs tyler-griggs commented Apr 8, 2026

Summary

  • The uv.lock regeneration in [megatron] support qwen3.5 models for megatron, bump mbridge + megatron-core to latest #1425 bumped griffe2md from 1.3.4 to 1.5.0, which renders docstring content slightly differently
  • A <= operator at the start of a line in the FullyAsyncConfig docstring (skyrl/train/config/config.py:394) was left unescaped in the MDX output, causing the Next.js MDX parser to fail with: Unexpected character '=' (U+003D) before name
  • Adds a second regex pass in sanitize_for_mdx() that escapes any bare < not followed by a valid HTML tag-start character (letter, /, !)

Open with Devin

The uv.lock regeneration in #1425 bumped griffe2md from 1.3.4 to 1.5.0,
which renders docstring content slightly differently. A `<=` operator at
the start of a line in the FullyAsyncConfig docstring was left unescaped
in the MDX output, causing the Next.js MDX parser to interpret `<` as the
start of a JSX tag and fail with:

  Unexpected character `=` (U+003D) before name

Add a second regex pass in `sanitize_for_mdx()` that escapes any `<` not
followed by a valid tag-start character (letter, `/`, `!`), converting
patterns like `<=` to `&lt;=`.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tyler-griggs tyler-griggs marked this pull request as ready for review April 8, 2026 17:53
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

Open in Devin Review

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the docs/generate-api-docs.py script to escape bare < characters in docstrings, preventing MDX parsing errors for sequences like <= or <2. Feedback was provided to compile the regular expression outside the loop to improve performance and readability.

Comment thread docs/generate-api-docs.py
Comment on lines +295 to +299
part = re.sub(
r"<(?![a-zA-Z/!])",
r"&lt;",
part,
)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For improved performance and readability, it's a best practice to compile regular expressions that are used inside a loop. This regex is recompiled on every iteration within the loop over parts of a line.

You could define the compiled regex object once, before the for line in lines: loop, and reuse it. For example:

# Before the loop
_bare_lt_re = re.compile(r"<(?![a-zA-Z/!])")

# Inside the loop
...
part = _bare_lt_re.sub(r"&lt;", part)

This advice also applies to the other regular expression substitution for invalid tags just above this change.

@SumanthRH SumanthRH merged commit 4974969 into main Apr 8, 2026
2 checks passed
@erictang000 erictang000 deleted the fix/docs-mdx-escape-bare-angle-brackets branch April 8, 2026 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants