pomber / docusaurus-mdx-2

A Docusaurus theme to add support for MDX v2

Docusaurus Theme MDX v2

This is a Docusaurus theme to add support for MDX v2 until it is officially supported.

Installation

1. Upgrade Docusaurus to version 2.0.0-beta.18 or later
2. Upgrade your @mdx-js/react dependency to version ^2.0.0
3. Install docusaurus-theme-mdx-v2

npm install docusaurus-theme-mdx-v2

4. Add mdx-v2 theme to your docusaurus.config.js

// ...
const config = {
  //...
  presets: [...],
  themes: ["mdx-v2"],
  themeConfig: ...
  //...
}
// ...

5. Migrate your .md and .mdx files to MDX v2 if you need. The most common breaking changes are:

• You cannot use comments like this <!--comment--> anymore. Now you should use something like {/* prettier-ignore */}
• You need to escape { in your prose like this \{
• If you are using components that aren't imported or part of the MDXComponents, MDX v2 will throw an error (v1 only showed a warning)

Known Issues

Admonitions syntax doesn't work with MDX v2

Instead of using the markdown syntax for admonitions, you should use the <Admonition /> component.

Instead of this:

:::note Your Title

Some **content** with _markdown_ `syntax`.

:::

Use this:

import Admonition from '@theme/Admonition'

<Admonition type="note" title="Your Title">

Some **content** with _markdown_ `syntax`.

</Admonition>

License

MIT

docusaurus-mdx-2's Issues

Headings wrapped inside JSX not included in TOC

For example:

## h2 1

<div>

## h2 2

### h3

</div>

TOC only shows "h2 1"

Background color will not change with Shiki themes

When I change Shiki syntax highlighting themes, the syntax highlighting colors will change, but the codeblock background remains the same dark color. I suppose this can be changed with CSS, but It would be nice to have the background change with the theme rather than adding custom CSS.

Errors returned with Remark plugins

I want to use the katex and math remark plugins for parsing formulas, but I am getting errors:

Could not parse expression with acorn: Unexpected character '@'

It seems this happens to other remark plugins as well, such as the admonitions plugin (as specified in this repo's readme). I'd also like to use the directives plugin for simpler syntax, but am running into the same issue.

Is there any workaround for this, so I can still use Code Hike and these plugins?

Thanks

Wrapping MDXComponents not working anymore

I have noticed that once activating the theme, the extension I have done through wrapping MDXComponents is not picked up anymore.

That is, the example in the original documentation of docusaurus that shows how to extend the component scope via MDXComponent.js is not working correctly anymore.

import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';

export default {
  // Re-use the default mapping
  ...MDXComponents,
  // Map the "highlight" tag to our <Highlight /> component!
  // `Highlight` will receive all props that were passed to `highlight` in MDX
  highlight: Highlight,
};

new code in Scrollycode blocks won't render reliably

If I change a scrollycode block to add code, the output will not show correctly. Often the codeblock output breaks or will not display the correct code.

In the following example, I would like to use this feature to introduce each command as a new line of code added to the Scrollycode block output:

<CH.Scrollycoding>

1. Make a new directory.

```sh focus=1:2
mkdir my-app
cd my-app
```

---

2. Set 'stable' as the default release channel.

```sh focus=4
mkdir my-app
cd my-app

rustup default stable
```

---

3. Add WASM as the compilation target.


```sh focus=6
mkdir my-app
cd my-app

rustup default stable

rustup target add wasm32-unknown-unknown

```

---

4. Install the following packages to generate the contract.


```sh focus=8:9
mkdir my-app
cd my-app

rustup default stable

rustup target add wasm32-unknown-unknown

cargo install cargo-generate --features vendored-openssl
cargo install cargo-run-script

```
</CH.Scrollycoding>

This occurs when testing locally with npm run start using Safari or Chrome browser.