`mdx-code-block` doesn't work when indented

SilianZ commented 3 months 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

I'm using Crowdin to translate my Docaurus MDX documents. In order to make the text displayed correctly on Crowdin, I added mdx-code-block to my document according to the official document to convert the text into a code block.

According to my research on some official documents, this is probably because I didn't install @docausaurus/utils, but the document does not clearly state that I need to install this package. If possible, please improve the content of this part of the document.

Here is my source code:

    ```mdx-code-block
    <Tabs>
    <TabItem value="c1" label="下载 Release" default>

1. 从 [Releases](https://github.com/TTB-Network/python-openbmclapi/releases) 中下载代码。

2. 将下载好的源码放到一个事先准备的文件夹。

3. 在文件夹中打开终端。

```mdx-code-block
</TabItem>
<TabItem value="c2" label="使用 Git 克隆">
```

1. 克隆仓库：

    ```sh
    git clone https://github.com/TTB-Network/python-openbmclapi.git
    ```

    :::tip

    你亦可以使用镜像源加速：

    ```sh
    git clone https://ghproxy.bugungu.top/https://github.com/TTB-Network/python-openbmclapi.git
    ```

    :::

2. 打开仓库所在文件夹：

    ```sh
    cd python-openbmclapi
    ```

```mdx-code-block
<Asciinema
url="https://asciinema.org/a/655199.cast"
options={{
    theme: "monokai",
    poster: "npt:21.5",
    cols: 100,
    rows: 30,
    idleTimeLimit: 0.2,
}}
/>

</TabItem>
</Tabs>

```



### Reproducible demo

_No response_

### Steps to reproduce

1. Create **MDX** files through source code.
2. Start the site.

### Expected behavior

According to the description of the document, the content of the `mdx-code-block` code block will be automatically recognized as JSX content.

### Actual behavior

However…

<img width="590" alt="image" src="https://github.com/facebook/docusaurus/assets/113701655/24bef9a6-3464-4269-8688-1ca1a6ee700d">

### Your environment

- Public source code: https://github.com/TTB-Network/python-openbmclapi-site
- Docusaurus version used: 3.4.0

### Self-service

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

Josh-Cena commented 3 months ago

According to my research on some official documents, this is probably because I didn't install @docausaurus/utils,

No you don't need to.

The issue is that you cannot indent your mdx-code-blocks. We only recognize these code blocks if they are placed at the absolute beginning of a line.

SilianZ commented 3 months ago

According to my research on some official documents, this is probably because I didn't install @docausaurus/utils,

No you don't need to.

The issue is that you cannot indent your mdx-code-blocks. We only recognize these code blocks if they are placed at the absolute beginning of a line.

So… Is it a bug?

Josh-Cena commented 3 months ago

Yeah I think so.

slorber commented 3 months ago

This is a bug/limitation yes.

Unfortunately we don't really plan to fix it, because it the mdx-code-block thing is a limitation of the current system. The mdx-code-block is a best-effort that will not work in all situations because we don't use a real Markdown parser to "unwrap" the blocks

    ```mdx-code-block
    <Tabs>
    <TabItem value="c1" label="下载 Release" default>


To support this with a real Markdown parser and support edge cases properly, we would have to write a remark plugin. 

Unfortunately, writing a remark plugin has limitations too, and what's inside of the code block would have to be valid MDX. Your code block content is not valid MDX, so this "proper solution" would not even handle your case like you'd expect, because this errors:

![CleanShot 2024-06-17 at 16 35 29](https://github.com/facebook/docusaurus/assets/749374/ab9aa81f-7c4f-4030-8338-760a0e177cc2)

The thing is, you can't parse MDX fragments in "slices", you have to have valid JSX markup. To parse this properly, you would have to write the whole JSX inside the code block, which is not ideal because now there's translatable content appearing inside the code block:

````md
    ```mdx-code-block
    <TabItem value="c1" label="下载 Release" default>

1. 从 [Releases](https://github.com/TTB-Network/python-openbmclapi/releases) 中下载代码。

2. 将下载好的源码放到一个事先准备的文件夹。

3. 在文件夹中打开终端。

```mdx-code-block
</TabItem>
```



---

For these reasons even if the current system is imperfect, I think it is good enough and the right tradeoff for our usage.

If nesting is a problem, you can try to isolate the nested mdx-code-block inside a partial

slorber commented 3 months ago

Hmm, that being said it should be relatively easy to handle nesting in our unwrapMdxCodeBlocks function

SilianZ commented 3 months ago

Hey! How can I get the Canary version after this bug is fixed, or can I only wait for the release of the new version?

OzakIOne commented 3 months ago

Hey! How can I get the Canary version after this bug is fixed, or can I only wait for the release of the new version?

Here is the guide on how to use canary versions until the fix is included in the next release : https://docusaurus.io/community/canary

facebook / docusaurus