https://github.com/pomber/docusaurus-mdx-2
A Docusaurus theme to add support for MDX v2
https://github.com/pomber/docusaurus-mdx-2
docusaurus docusaurus-theme mdx
Last synced: about 1 month ago
JSON representation
A Docusaurus theme to add support for MDX v2
- Host: GitHub
- URL: https://github.com/pomber/docusaurus-mdx-2
- Owner: pomber
- Created: 2022-04-08T14:57:23.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-07-20T13:42:39.000Z (almost 3 years ago)
- Last Synced: 2024-04-26T10:44:39.368Z (about 1 year ago)
- Topics: docusaurus, docusaurus-theme, mdx
- Language: TypeScript
- Homepage: docusaurus-mdx-2.vercel.app
- Size: 595 KB
- Stars: 27
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# Docusaurus Theme MDX v2
This is a Docusaurus theme to add support for MDX v2 [until it is officially supported](https://github.com/facebook/docusaurus/issues/4029).
## 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`
```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 `` 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
`` component.
Instead of this:
```md
:::note Your Title
Some **content** with _markdown_ `syntax`.
:::
```
Use this:
```md
import Admonition from '@theme/Admonition'
Some **content** with _markdown_ `syntax`.
```
## License
MIT