difficulty with code blocks in v2

[godmar]

I'm following this documentation and created a component CodeBlock.

I include it in my MDXProvider like so:

const components = {
   code: CodeBlock
}

However, it has the following issues.

• It's being used for both single backquotes like this as well as triple backquote blocks.
• When used for the latter, it adds an extra newline
• The property className is not set, which triggers an error.

The update guide says: The special component name inlineCode was removed, we recommend to use pre for the block version of code, and code for both the block and inline versions.

Does this mean that the code component now has to be "smart" enough to find out whether it's a single pair of backquotes or a triple-backquote code section?

[godmar]

Specifically, this mdx:

# Code

new `new`

```bash
# In your ~/.bash_profile
export PATH=~work/bin:$PATH
```

seems to be compiled into:

return _jsxs(_Fragment, {
      children: [_jsx(_components.h1, {
        children: "Code"
      }), "\n", _jsxs(_components.p, {
        children: ["new ", _jsx(_components.code, {
          children: "new"
        })]
      }), "\n", _jsx(_components.pre, {
        children: _jsx(_components.code, {
          className: "language-bash",
          children: "# In your ~/.bash_profile\nexport PATH=~work/bin:$PATH\n"
        })
      })]
    });

where the first invocation of _components.code doesn't pass a className and where both types of code (inline and block) are mapped to the same component, name code, but why?

[godmar]

Following the suggestion to check for the className field taken from here I came up with the following syntax highlighter component, which turns single backquote sections into HTML <code> and otherwise invokes the highlighter:

import React from 'react'
import Highlight, {defaultProps} from 'prism-react-renderer'
import duotoneLight from 'prism-react-renderer/themes/duotoneLight';

export default (props) => {
  const {className, ...rest} = props;
  const match = /language-(\w+)/.exec(className || '')

  if (match) {
    const language = match[1];
    const body = rest.children.trim();  // remove leading and trailing newlines
    return (
      <Highlight {...defaultProps} code={body} language={language} theme={duotoneLight}>
        {({className, style, tokens, getLineProps, getTokenProps}) => (
          <pre className={className} style={{...style, padding: '20px'}}>
            {tokens.map((line, i) => (
              <div key={i} {...getLineProps({line, key: i})}>
                {line.map((token, key) => (
                  <span key={key} {...getTokenProps({token, key})} />
                ))}
              </div>
            ))}
          </pre>
        )}
      </Highlight>
    )
  } else { 
    return <code className={className} {...props} />
  }
}

Is this the recommended approach?

[ChristianMurphy]

I'm following this documentation and created a component CodeBlock.

The page you linked, isn't the documentation page for using code blocks.
Have you tried the guide on the website? https://mdxjs.com/guides/syntax-highlighting/

Does this mean that the code component now has to be "smart" enough to find out whether it's a single pair of backquotes or a triple-backquote code section?

Yes, how to do this is documented at https://mdxjs.com/guides/syntax-highlighting/

where both types of code (inline and block) are mapped to the same component, name code, but why?

For the same reason you mentioned in your original question and in the update guide

The special component name inlineCode was removed, we recommend to use pre for the block version of code, and code for both the block and inline versions.

because markdown is transformed to HTML, and inlineCode is not an HTML element.

Is this the recommended approach?

The approaches in https://mdxjs.com/guides/syntax-highlighting/ are recommended.
You are welcome to remix them as needed.

[godmar]

I'm following this documentation and created a component CodeBlock.

The page you linked, isn't the documentation page for using code blocks. Have you tried the guide on the website? https://mdxjs.com/guides/syntax-highlighting/

I'm sorry, this was a copy and paste mistake.

I meant to link to https://github.com/mdx-js/mdx/blob/master/docs/guides/syntax-highlighting.mdx#all-together

[godmar]

Apparently, the mdx repo has both a master and a main branch.
Google searches show the master branch (presumably because Google is racist), so that's how I found https://github.com/mdx-js/mdx/tree/master/docs/guides

master is however 309 commits behind main.

Perhaps there is a way to remove the master branch or add a note that it's out of date?

[wooorm]

master is however 309 commits behind main.

^-- this is shown at the top of each page

Perhaps there is a way to remove the master branch or add a note that it's out of date?

Renamed master to v1, though I doubt that’ll change Google or what you see

[godmar]

PS: following the approach documented here still has the issue of the trailing newline causing an additional empty line, so adding

props.children = props.children.trim()

is still necessary.

Also, FWIW, in next.js at least I couldn't get the first approach, even though I added the plugin to rehypePlugins in next.config.js as described here.

[wooorm]

I do not know how to debug your last example, as there is no code to comment on

[godmar]

I do not know how to debug your last example, as there is no code to comment on

I meant I completed the example given by adding this line. The complete code is

export function CodeBlock2({className, ...props}) {
  props.children = props.children.trim()
  const match = /language-(\w+)/.exec(className || '')
  return match
    ? <SyntaxHighlighter language={match[1]} PreTag="div" {...props} />
    : <code className={className} {...props} />
}

without trimming the string (removing trailing newlines, in particular), an extra empty line is rendered by SyntaxHighlighter

This is analogous to the line const body = rest.children.trim() above

[ChristianMurphy]

Also, FWIW, in next.js at least I couldn't get the first approach, even though I added the plugin to rehypePlugins in next.config.js as described here.

@next/mdx is maintained at https://github.com/vercel/next.js, the next team may be able to provide more context on why it isn't working https://github.com/vercel/next.js/discussions

That said you don't need to use @next/mdx, @mdx-js/loader can be used directly with next without a wrapper https://mdxjs.com/docs/getting-started/#nextjs
and supports rehype-highlight, for example: https://codesandbox.io/s/mdx-loader-with-rehype-highlight-nu41j

example next.config.mjs

// ⚠️ Important! Please make sure the dependencies are up to date.

import rehypeHighlight from 'rehype-highlight'

const configuration =  {
  // Support MDX files as pages:
  pageExtensions: ["md", "mdx", "tsx", "ts", "jsx", "js"],
  // Support loading `.md`, `.mdx`:
  webpack(config, options) {
    config.module.rules.push({
      test: /\.mdx?$/,
      use: [
        // The default `babel-loader` used by Next:
        options.defaultLoaders.babel,
        {
          loader: "@mdx-js/loader",
          /** @type {import('@mdx-js/loader').Options} */
          options: {
            /* jsxImportSource: …, otherOptions… */
            rehypePlugins: [rehypeHighlight]
          },
        },
      ],
    });

    return config;
  },
};

export default configuration

[ChristianMurphy]

rehype-highlight is ESM only since version 5 https://github.com/rehypejs/rehype-highlight/releases/tag/5.0.0

[godmar]

I would need to know the tradeoffs/risks involved in changing next.config to ESM.

[ChristianMurphy]

There is an introduction to ESM at https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
And you can follow the discussion where Next added support here vercel/next.js#9607

TL;DR
ESM can statically or dynamically import CJS and ESM.
CJS can only dynamically require CJS and can only dynamically import ESM.

[godmar]

Ok, I tried it. With next.config.mjs it works using the example you gave.

I installed highlight and added its CSS to /pages/_app.js using import 'highlight.js/styles/default.css'.

[godmar]

If you find it useful, I proposed adding a note here #1894

[godmar]

I have a follow-up question. How/where do I configure languages for the rehype-highlight plugin that's recommended?
I'm trying to use x86asm and asm which are not registered.

[wooorm]

How to use plugins is documented in “Using plugins” section of the “Extending MDX” article