Docs: Treat changelog as a markdown file#3531
Merged
Conversation
The docs site renders changelog.md as MDX, so a PR title like
`@php-wasm/{web,node}-5-2` gets parsed as a JSX expression and the
build crashes with "ReferenceError: web is not defined". Escape
`{` and `}` when copying the changelog into the docs, and unbreak
the v3.1.21 entry that's currently failing CI on trunk.
adamziel
added
[Type] Documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Fixes Docusaurus/MDX changelog rendering failures by preventing brace-delimited text in release notes from being interpreted as MDX/JS expressions.
Changes:
- Escapes
{and}in the v3.1.21 changelog entry referencing@php-wasm/{web,node}-5-2 - Cleans up stray/indented blank lines in the changelog
Comments suppressed due to low confidence (3)
packages/docs/site/docs/main/changelog.md:1
- Escaping braces with backslashes works in many Markdown parsers, but in MDX the most robust way to prevent
{...}from being treated as an expression is to wrap the package name in an inline code span. Consider formatting the package name as inline code (e.g., using backticks) instead of relying on\\{/\\}escaping.
---
packages/docs/site/docs/main/changelog.md:1
- This change alters the meaning of the original token
__DIR__by turning it into bold text (**DIR**). If the goal is to prevent Markdown/MDX emphasis parsing of underscores, keep the token intact by rendering it as inline code (preferred) or escaping underscores so the rendered output still shows__DIR__.
---
packages/docs/site/docs/main/changelog.md:1
- The PR description mentions updating the refresh script to escape
{and}during the copy step, but this diff only shows a manual edit to the generated changelog in docs. If the script change is intended as part of this PR, it looks missing from the current changeset.
---
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Setting `format: md` in the file's frontmatter tells Docusaurus to parse it as CommonMark, which means braces and angle brackets in PR titles render as literals. That removes the need for the brace-escaping hack the previous commit added to refresh-changelog.ts.
adamziel
changed the title
2 tasks
adamziel
added a commit
that referenced
this pull request
Apr 27, 2026
The previous fix in #3531 added a `format: md` frontmatter to `changelog.md` and assumed Docusaurus would parse it as plain CommonMark. It does not — at least not in 3.9.2 with our current config. The CI run on trunk for that very commit still crashed on `@php-wasm/{web,node}-5-2` with `ReferenceError: web is not defined`, taking out `test-docs-api-reference` and the docs deploy. This PR makes the content itself inert instead of relying on Docusaurus mode: `refresh-changelog.ts` now backslash-escapes `{` and `}` in the copied changelog body, and the broken v3.1.21 entry is escaped directly so trunk goes green. ## Test plan - [ ] `test-docs-api-reference` passes - [ ] `Deploy doc site` passes
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
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
The
chore: update changelogbot has been failing CI on trunk since v3.1.21. Docusaurus parsespackages/docs/site/docs/main/changelog.mdas MDX, so the auto-generated entry for PR #3506 —@php-wasm/{web,node}-5-2— was read as a JSX expression and crashed the SSG withReferenceError: web is not defined. That took out bothtest-docs-api-referenceandDeploy doc site.This PR treats the changelog as a markdown file, not MDX.
Test plan
test-docs-api-referencepassesDeploy doc sitepasses