[Docusaurus] {=mdx} code block seems broken (Quarto 1.4 with Docusaurus v3)

[eitsupi]

Bug description

If we use mdx in mdx files, it doesn't seem necessary to write it as code blocks.

``` mdx-code-block should be changed to ```mdx-code-block

Steps to reproduce

---
title: foo
format: docusaurus-md
---

```{=mdx}
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

Expected behavior

---
title: foo
format: docusaurus-md
---



```mdx-code-block
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

Actual behavior

---
title: foo
format: docusaurus-md
---




``` mdx-code-block
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

Your environment

• Ubuntu 22.04

Quarto check output

$ quarto check   
Quarto 1.4.545
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.4.545
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Tex:  (not detected)

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.10.12
      Path: /usr/local/python/current/bin/python3
      Jupyter: 5.7.1
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.2
      Path: /usr/local/lib/R
      LibPaths:
        - /workspaces/querying-with-prql/renv/library/R-4.3/x86_64-pc-linux-gnu
        - /usr/local/lib/R/library
      knitr: 1.45
      rmarkdown: 2.25

[✓] Checking Knitr engine render......OK

[cderv]

This mdx-code-block syntax was added in b761219

I believe this happened before the change to .mdx extension in e86312c

I don't have much context but looking at the docusaurus doc, it seems to be interesting syntax related to mdx support in some situation with specific tools, according to doc at https://docusaurus.io/docs/i18n/crowdin#mdx

Does the use of code block mdx-code-block creates an issue with Docusuarus rendering ?

Doc says it should be

interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block)

it was also mentioned in V1 to V2 migration guide : https://docusaurus.io/docs/migration/v2/translated-sites

So it does not seem necessary indeed but seems useful to protect the output for some situations

@jjallaire do you remember about b761219 and using

function RawBlock(el)
  if el.format == 'mdx' then
    return pandoc.CodeBlock(el.text, pandoc.Attr("", {"mdx-code-block"}))

Was it necessary for some specific reason ? or dependant of docusaurus version ?

[eitsupi]

Does the use of code block mdx-code-block creates an issue with Docusuarus rendering ?

In Docusaurus v3.0.1, which I tried, the mdx-code-block code block seems to be displayed on the website as a code block.

[eitsupi]

Thanks for the link to the documentation. This seems to be supported by Docusaurus 3.1.0, so maybe it's a bug of Docusaurus...

[cderv]

I understand the Docusaurus V3 is a big change, especially about MDX V1 to V3 : https://docusaurus.io/docs/migration/v3#upgrading-mdx

I am not sure exactly which version we support but I would say it is Docusaurus V2 because v3 is out since 31 October 2023 so not that long. So I would not surprise to find issues. @cscheid did we do specific work for Docusaurus V3 and upgrade to MDX v1 to v3 ?

I am not sure and we probably need to check what Quarto is producing and adapt.

[eitsupi]

Now I know what the problem is.
Spaces before the infostring are not allowed.
In other words, it should be ```mdx-code-block, not ``` mdx-code-block

v.s.

[krishaamer]

``` mdx-code-block should changed be ```mdx-code-block

I can confirm on my project (Quarto 1.4.545 and Docusaurus 3.1.0 on MacOS Ventura) that removing the additional space after ``` immediately fixes the rendering. Hope this gets fixed soon. @cderv

[eitsupi]

Or, should it be modified to ignore the space before the infostring on the Docusaurus side (mdx side)?

[eitsupi]

This seems to be handled with a simple regular expression. It might be easy to update it to ignore spaces.
https://github.com/facebook/docusaurus/blob/604ccaa89c46dd2e3b515e1beeefa52454447650/packages/docusaurus-utils/src/markdownUtils.ts#L70-L75

[cderv]

Thanks for finding this.

It seems they could indeed add support for space in their regex. I believe this is common and they support it for other codeblocks.

On our side, the space is added by Pandoc directly, as this is the Markdown syntax created from Lua

> pandoc -f native -t markdown_strict+fenced_code_blocks+backtick_code_blocks
CodeBlock ("",["mdx-code-block"],[]) "content"

``` mdx-code-block
content
```

It could also be seen as an improvement on Pandoc's side because they do not document with space in their doc (https://pandoc.org/MANUAL.html#fenced-code-blocks) but they do consider space as the created syntax if I try round-trip

> pandoc -f markdown -t markdown
```haskell
qsort [] = []
```

``` haskell
qsort [] = []
```

From their doc:

If the fenced_code_attributes extension is disabled, but input contains class attribute(s) for the code block, the first class attribute will be printed after the opening fence as a bare word.

To fix this in Pandoc we would need to create ourself raw markdown instead of a CodeBlock at

quarto-cli/src/resources/extensions/quarto/docusaurus/docusaurus.lua

Lines 52 to 56 in 9e35ab3

	-- transform 'mdx' into passthrough content, transform 'html'
	-- into raw commamark to pass through via dangerouslySetInnerHTML
	local function RawBlock(el)
	if el.format == 'mdx' then
	return pandoc.CodeBlock(el.text, pandoc.Attr("", {"mdx-code-block"}))

[eitsupi]

Thanks.

IIUC, this is a bug that occurred between Docusaurus v2 and v3 and can convince them to ignore the space.

Until tomorrow I don't have time to do any more research or report or PR to the docusaurus repo, but I'll take a look at this on Saturday if someone doesn't.

[cderv]

I opened a PR with a change that should fix this - But this indeed maybe on docusaurus itself to have broader support.

[eitsupi]

FYI, the issue of Docusaurus has been fixed by facebook/docusaurus#9776
Maybe v3.1.1 includes that...