Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
elitalpa wants to merge 1 commit into from
Closed

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions src/content/learn/building-a-react-framework.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -33,7 +33,7 @@ The first step is to install a build tool like `vite`, `parcel`, or `rsbuild`. T
[Vite](https://vite.dev/) is a build tool that aims to provide a faster and leaner development experience for modern web projects.

<TerminalBlock>
npm create vite@latest my-app -- --template react
{`npm create vite@latest my-app -- --template react`}

@harish-sethuramanharish-sethuramanFeb 17, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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.

@elitalpaelitalpaFeb 17, 2025•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

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.

@elitalpaelitalpaFeb 17, 2025•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

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

@rickhanloniirickhanloniiFeb 17, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

</TerminalBlock>

Vite is opinionated and comes with sensible defaults out of the box. Vite has a rich ecosystem of plugins to support fast refresh, JSX, Babel/SWC, and other common features. See Vite's [React plugin](https://vite.dev/plugins/#vitejs-plugin-react) or [React SWC plugin](https://vite.dev/plugins/#vitejs-plugin-react-swc) and [React SSR example project](https://vite.dev/guide/ssr.html#example-projects) to get started.
Expand All@@ -45,7 +45,7 @@ Vite is already being used as a build tool in one of our [recommended frameworks
[Parcel](https://parceljs.org/) combines a great out-of-the-box development experience with a scalable architecture that can take your project from just getting started to massive production applications.

<TerminalBlock>
npm install --save-dev parcel
{`npm install --save-dev parcel`}
</TerminalBlock>

Parcel supports fast refresh, JSX, TypeScript, Flow, and styling out of the box. See [Parcel's React recipe](https://parceljs.org/recipes/react/#getting-started) to get started.
Expand All@@ -55,7 +55,7 @@ Parcel supports fast refresh, JSX, TypeScript, Flow, and styling out of the box.
[Rsbuild](https://rsbuild.dev/) is an Rspack-powered build tool that provides a seamless development experience for React applications. It comes with carefully tuned defaults and performance optimizations ready to use.

<TerminalBlock>
npx create-rsbuild --template react
{`npx create-rsbuild --template react`}
</TerminalBlock>

Rsbuild includes built-in support for React features like fast refresh, JSX, TypeScript, and styling. See [Rsbuild's React guide](https://rsbuild.dev/guide/framework/react) to get started.
Expand Down