Header ID syntax is not compatible with MDXv2's syntax for embedding expressions

tats-u commented 1 year ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] I'm using the latest version of Docusaurus.
[ ] I have tried the npm run clear or yarn clear command.
[ ] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
[ ] I have tried creating a repro with https://new.docusaurus.io.
[ ] I have read the console error message carefully (if applicable).

Description

(WIP)

# foo {#id}

vs

1 + 1 = {1 + 1}

The language server in the MDX extension for VS Code show a syntax error on the header syntax. I believe the current syntax using single braces is no longer approved. Double parens ((#id)) is an alternative.

Reproducible demo

WIP

Steps to reproduce

Enable the language server
Add a header with its ID

Expected behavior

No errors

Actual behavior

Syntax error

Your environment

Public source code:
Public site URL:
Docusaurus version used:
Environment name and version (e.g. Chrome 89, Node.js 16.4):
Operating system and version (e.g. Ubuntu 20.04.2 LTS):

WIP

Self-service

[ ] I'd be willing to fix this bug myself.

Josh-Cena commented 1 year ago

This is already addressed in v3. See for example: https://github.com/facebook/docusaurus/pull/8788

tats-u commented 1 year ago

It's good to know. Sorry for the lack of a detailed investigation. I was going to look into v3 using my desktop (this issue is written using my cellphone).

slorber commented 1 year ago

v3 will keep supporting the old legacy syntax.

However, your VSCode might still report syntax errors, which can be annoying, because indeed it's not valid in MDX 2 anymore.

A temporary workaround if you want things to work in VSCode + Docusaurus is to use # foo \{#id} (that's basically what the mdx1 compat layer does, it escapes the expression block)

I think it's worth reopening this issue: the current setup probably doesn't prevent you from upgrading to Docusaurus v3, but we still need to find a solution (new syntax) that works out of the box with MDX 2, and a migration plan for our users. That's better in the long-term, for compatibility with VSCode, Prettier, ESLint, and all other external tools that understand MDX 2.

@wooorm has suggested doing like the new React website, using MDX comments: # foo {/* id */}

There are other implications to consider, like how our recommended translation SaaS Crowdin will understand such syntax once they have better support for MDX (which they are working on). For these reasons, I have delayed that syntax decision.

dejongbaba commented 7 months ago

Hello , can I take a look at this bug ?

OzakIOne commented 7 months ago

Hello , can I take a look at this bug ?

Hello @dejongbaba Docusaurus maintainers don't assign issues or bugs to anyone, if you want to work on this feel free to send directly a PR that fixes the issue / bug

facebook / docusaurus