Skip to content

docs: put the <Mac> notification text in code so the website builds - #2057

Merged
janicduplessis merged 1 commit into
mainfrom
fix/2056-docs-mdx-mac
Sep 30, 2026
Merged

janicduplessis merged 1 commit into
mainfrom
fix/2056-docs-mdx-mac

Conversation

@janicduplessis

Copy link
Copy Markdown
Collaborator

Description

The Docs workflow fails on every push to main since #1839 added "<Mac> wants to build on this Mac" to website/docs/desktop.md. MDX parses <Mac> as a JSX tag: Expected a closing tag for <Mac> (255:32-255:37) (run 36731674612). The site has not deployed since.

Solution

Put the notification text in inline code, which renders the placeholder literally. The Docusaurus build succeeded afterwards, so no other bare placeholder breaks MDX. The same escape exists in draft PR #2054; it is dropped from that branch so it can stay a draft until the first desktop release.

CI does not build the website on pull requests (docs.yml runs only on push to main); a follow-up is noted in the issue.

Test plan

  • pnpm --filter website run build fails on main's file and succeeds with this change.
  • pnpm run format:check passes.
  • The Docs run on main after merge succeeds.

Fixes #2056

@janicduplessis janicduplessis left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Reviewed the diff, issue #2056, and the other MDX inputs. No blocking findings.

  • The change is one line in website/docs/desktop.md:255. The notification text moves from double quotes to inline code, which stops MDX from reading <Mac> as a JSX tag. It matches the error in the issue (Expected a closing tag for <Mac> at 255:32-255:37).
  • I scanned every file in website/docs on origin/main, with fenced blocks and inline code spans removed, for bare <Word> or { outside JSX. Nothing else would break MDX. The only hits were the intended components (StimTabs, PromptBox, PromptGrid, StimInstallTabs) and two multi-line inline code spans, at commands.md:646 (<name>) and owned-devices.md:505, which are fine.
  • Generated docs sources are also fine. gen-troubleshooting.mjs already escapes < and { outside code spans (escapeMdx). gen-changelog.mjs does no escaping, so I scanned all 42 docs/releases/*.md files with the same check and found nothing that would break.
  • The rendered text now reads as a literal notification string in monospace. The quotes are gone, but the code style still marks it as the exact text. That is fine.

Not part of this PR: the issue's follow-up to build the website on PRs touching website/** is still open, and it is the only thing that would have caught this before merge.

@janicduplessis
janicduplessis marked this pull request as ready for review September 30, 2026 15:22
@janicduplessis
janicduplessis merged commit b698716 into main Sep 30, 2026
8 checks passed
@janicduplessis
janicduplessis deleted the fix/2056-docs-mdx-mac branch September 30, 2026 15:23
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.

Website build fails on <Mac> placeholder in desktop.md

1 participant