3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-02 08:19:07 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat: upgrade to MDX v2 (#8288)

Browse source 
Co-authored-by: Armano <armano2@users.noreply.github.com>
This commit is contained in:
Sébastien Lorber 2023-04-21 19:48:57 +02:00 • committed by GitHub
parent 10f161d578
commit bf913aea2a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
161 changed files with 4028 additions and 2821 deletions
Download patch file Download diff file Expand all files Collapse all files

35
website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
<!-- prettier-ignore -->
{/* prettier-ignore */}
```md
<!-- Prettier doesn't change this -->
:::note
@ -110,9 +110,9 @@ Hello world
You may also specify an optional title.
```md
:::note Your Title
:::note[Your Title **with** some _Markdown_ `syntax`!]
Some **content** with _Markdown_ `syntax`.
Some **content** with some _Markdown_ `syntax`.
:::
```
@ -120,9 +120,9 @@ Some **content** with _Markdown_ `syntax`.
```mdx-code-block
<BrowserWindow>
:::note Your Title
:::note[Your Title **with** some _Markdown_ `syntax`!]
Some **content** with _Markdown_ `syntax`.
Some **content** with some _Markdown_ `syntax`.
:::
@ -186,7 +186,7 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::tip Use tabs in admonitions
:::tip[Use tabs in admonitions]
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
@ -200,7 +200,7 @@ import TabItem from '@theme/TabItem';
```mdx-code-block
<BrowserWindow>
:::tip Use tabs in admonitions
:::tip[Use tabs in admonitions]
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
@ -235,20 +235,16 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
```jsx title="MyReactPage.jsx"
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</Admonition>
```
```mdx-code-block
<BrowserWindow>
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</Admonition>
</BrowserWindow>
```
@ -286,7 +282,6 @@ module.exports = {
{
docs: {
admonitions: {
tag: ':::',
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
extendDefaults: true,
},
@ -299,9 +294,8 @@ module.exports = {
The plugin accepts the following options:
- `tag`: The tag that encloses the admonition. Defaults to `:::`.
- `keywords`: An array of keywords that can be used as the type for the admonition.
- `extendDefaults`: Should the provided options (such as `keywords`) be merged into the existing defaults. Defaults to `false`.
- `extendDefaults`: Should the provided options (such as `keywords`) be merged into the existing defaults. Defaults to `true`.
The `keyword` will be passed as the `type` prop of the `Admonition` component.
@ -321,7 +315,6 @@ module.exports = {
// ...
docs: {
admonitions: {
tag: ':::',
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
@ -361,7 +354,7 @@ export default AdmonitionTypes;
Now you can use your new admonition keyword in a Markdown file, and it will be parsed and rendered with your custom logic:
```md
:::my-custom-admonition Custom Admonition
:::my-custom-admonition[My Title]
It works!
@ -370,7 +363,7 @@ It works!
<BrowserWindow>
:::my-custom-admonition Custom Admonition
:::my-custom-admonition[My Title]
It works!

144
website/docs/guides/markdown-features/markdown-features-math-equations.mdx
View file

@ -54,27 +54,32 @@ $$
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
```bash npm2yarn
npm install --save remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0
npm install --save remark-math@5 rehype-katex@6
```
:::caution
Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
Make sure to use `remark-math >= 5` and `rehype-katex >= 6` for Docusaurus v3 (using MDX v2).
:::
Import the plugins in `docusaurus.config.js`:
Those 2 plugins are now only available as ESM packages, and you will need to import them dynamically.
```js
const math = require('remark-math');
const katex = require('rehype-katex');
First, turn your site config into an async config creator function:
```js title="docusaurus.config.js"
module.exports = async function createConfigAsync() {
return {
// your site config...
};
};
```
Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
It is now possible to import the plugins dynamically and add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
```js
remarkPlugins: [math],
rehypePlugins: [katex],
remarkPlugins: [(await import('remark-math')).default],
rehypePlugins: [(await import('rehype-katex')).default],
```
Include the KaTeX CSS in your config under `stylesheets`:
@ -94,39 +99,36 @@ stylesheets: [
Overall the changes look like:
```js title="docusaurus.config.js"
// highlight-start
const math = require('remark-math');
const katex = require('rehype-katex');
// highlight-end
module.exports = {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
// highlight-start
remarkPlugins: [math],
rehypePlugins: [katex],
// highlight-end
module.exports = async function createConfigAsync() {
return {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
// highlight-start
remarkPlugins: [(await import('remark-math')).default],
rehypePlugins: [(await import('rehype-katex')).default],
// highlight-end
},
},
],
],
// highlight-start
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
crossorigin: 'anonymous',
},
],
],
// highlight-start
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
crossorigin: 'anonymous',
},
],
// highlight-end
// highlight-end
};
};
```
@ -144,67 +146,3 @@ module.exports = {
],
};
```
## Upgrading rehype-katex beyond recommended version {#upgrading-rehype-katex-beyond-recommended-version}
:::tip
Only use the latest version if you actually need the bleeding-edge features of $\KaTeX$. Most users should find the older versions work just as well.
:::
The latest versions of `rehype-katex` (starting from `v6.0.0`) has moved to ES Modules, a new module system of JavaScript, which Docusaurus doesn't officially support yet. However, it is possible to import `rehype-katex` dynamically, using an async config creator. Docusaurus will call this creator function and wait for it to return the config object.
```js title="docusaurus.config.js"
async function createConfig() {
// ES Modules are imported with `import()` instead of `require()`, and are imported asynchronously
// highlight-next-line
const katex = (await import('rehype-katex')).default;
return {
// ...
};
}
```
In this case, the overall configuration changes will look like:
```js title="docusaurus.config.js"
// highlight-next-line
const math = require('remark-math');
async function createConfig() {
// highlight-next-line
const katex = (await import('rehype-katex')).default;
return {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
// highlight-start
remarkPlugins: [math],
rehypePlugins: [katex],
// highlight-end
},
},
],
],
// highlight-start
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ',
crossorigin: 'anonymous',
},
],
// highlight-end
};
}
module.exports = createConfig;
```

22
website/docs/guides/markdown-features/markdown-features-react.mdx
View file

@ -64,8 +64,8 @@ export const Highlight = ({children, color}) => (
<BrowserWindow minHeight={240}>
<Highlight color="#25c2a0">Docusaurus green</Highlight>
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
<><Highlight color="#25c2a0">Docusaurus green</Highlight>
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.</>
I can write **Markdown** alongside my _JSX_!
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
/* Instead of this: */
<span style="background-color: red">Foo</span>
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
You can also import your own components defined in other files or third-party components installed via npm.
<!-- prettier-ignore -->
{/* prettier-ignore */}
```md
<!-- Docusaurus theme component -->
import TOCInline from '@theme/TOCInline';
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
<div className={styles.wrappingBlock}>
```
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
<div style={{color: 'red'}}>
**Bold still doesn't work**
@ -367,7 +367,7 @@ Add an empty new line:
<div className={styles.wrappingBlock}>
```
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
<div style={{color: 'red'}}>
@ -397,7 +397,7 @@ Add an empty new line:
<div className={styles.wrappingBlock}>
```
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
<div style={{color: 'red'}}>
@ -427,7 +427,7 @@ Don't indent:
<div className={styles.wrappingBlock}>
```
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
<div style={{color: 'red'}}>
@ -463,14 +463,13 @@ npm install --save raw-loader
Now you can import code snippets from another file as it is:
<!-- prettier-ignore-start -->
{/* prettier-ignore */}
```jsx title="myMarkdownFile.mdx"
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
```
<!-- prettier-ignore-end -->
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
This is text some content from `_markdown-partial-example.mdx`.
```
<!-- prettier-ignore-start -->
{/* prettier-ignore */}
```jsx title="someOtherDoc.mdx"
import PartialExample from './_markdown-partial-example.mdx';
<PartialExample name="Sebastien" />
```
<!-- prettier-ignore-end -->
```mdx-code-block
import PartialExample from './_markdown-partial-example.mdx';

6
website/docs/guides/markdown-features/markdown-features-tabs.mdx
View file

@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
<!-- prettier-ignore-start -->
{/* prettier-ignore */}
```jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
</TabItem>
</Tabs>
```
<!-- prettier-ignore-end -->
```mdx-code-block
<BrowserWindow>
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
<!-- prettier-ignore-start -->
{/* prettier-ignore */}
```jsx title="some-doc.mdx"
import styles from './styles.module.css';
@ -266,7 +265,6 @@ import styles from './styles.module.css';
</TabItem>
</Tabs>
```
<!-- prettier-ignore-end -->
```css title="styles.module.css"
.red {

8
website/docs/guides/markdown-features/markdown-features-toc.mdx
View file

@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
A special Markdown syntax lets you set an **explicit heading id**:
```md
### Hello World {#my-explicit-id}
```mdx-code-block
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
```
:::tip
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
import TOCInline from '@theme/TOCInline';
@ -129,7 +129,7 @@ declare const toc: {
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
<!-- prettier-ignore -->
{/* prettier-ignore */}
```jsx
import TOCInline from '@theme/TOCInline';