fix(docs): prevent mdx from transforming -- into – for commands

[elitalpa]

Overview

• preventing mdx from transforming -- into – for commands ([Bug]: Can't copy the right command from the command block | double dashes -- gets merged into a single dash - #7616 )

Apparently any text in markdown gets processed and double dashes transformed.
If a command contains -- and we want it to be treated as a string, it should be put between {` and `} or between {" and "}.

Fixes #7616

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
19-react-dev	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 17, 2025 7:55am
react-dev	✅ Ready (Inspect)	Visit Preview		Feb 17, 2025 7:55am

[elitalpa]

Comparing

Notice the -- in commands.

Before

After

[github-actions]

Size changes

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[harish-sethuraman]

I dont think we should do this (making it string) We might want to check if this was working before and fix the root cause in TerminalBlock component. This component is in a lot of places.

[elitalpa]

Thanks for your comment, you are right to ask about the root cause and implications of this component being used in a lot of places so I've done more research into this.

not a bug but a feature ?

Actually it seems to be a feature of a markdown plugin that's causing this.
The plugin name is "retext-smartypants" and is implementing the smartypants syntax which transforms :

Dashes (“--” and “---”) into en- and em-dash entities
source (smartypant syntax docs) : daringfireball.net/projects/smartypants

The text inside the component gets treated as normal text because it's not put between {` `} or {" "} so it modifies the string before it gets to the TerminalBlock component.

Disabling this feature of the plugin might not be an option as this feature seem to be used in normal text across the docs.

Fast and Simple Solution

Putting the code between {` `} or {" "} makes the component receive the raw string.
This change doesn't need to be done everywhere, only when needed like here.

Using {` `} or {" "} or {' '} is something common in React's JSX syntax (the docs are written in MDX which is based on JSX) used for making sure certain characters are escaped when used as childrens of a component or html tag.

Alternative solution

The other alternative is to stop using the component directly but rather use markdown code blocks :
```bash
```
and maybe configure mdx to replace every code block with the TerminalBlock component. But this can require a lot more effort and impact many other pages.

[elitalpa]

tldr :

• root cause doesn't seem to be the TerminalBlock component but the retext-smartypants markdown plugin which transforms any text
• this feature of the plugin seems to be used across the docs and disabling it doesn't seem to be an option
• possibles solutions are
  • using curly braces (common in React) to escape characters
  • never using a React component for commands and using basic markdown codeblocks

[rickhanlonii]

Yeah the fix makes sense, we can fix it in terminal block if needed later

[rickhanlonii]

Thanks, merged this into #7624.

If you have a chance, it would be nice to audit all of the other usages to see if they have issues.

[elitalpa]

Thanks, merged this into #7624.

If you have a chance, it would be nice to audit all of the other usages to see if they have issues.

From what I noticed, other commands are not using the TerminalBlock component but a markdown code block like :

So this explains why there wasn't an issue like this previously.

Or -D is used instead of --save-dev :

✅ Checked all the other usages, there seems to be no issue.