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

docs: v2 docs should discourage the usage of a lower-case MDX component (will not work in v3) (#8779)

Browse source
This commit is contained in:
Sébastien Lorber 2023-03-16 15:23:55 +01:00 • committed by GitHub
parent 5c271f5622
commit 88b6f5fc68
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 76 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -152,16 +152,16 @@ For example, given this MDX file:
- a - a
- list! - list!
And some <highlight>custom markup</highlight>... And some <Highlight>custom markup</Highlight>...
``` ```
It will be compiled to a React component containing `ul`, `li`, `p`, and `highlight` tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (`highlight` isn't even an intrinsic element: it needs an implementation!) It will be compiled to a React component containing `ul`, `li`, `p`, and `Highlight` elements. `Highlight` is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations. In Docusaurus, the MDX component scope is provided by the `@theme/MDXComponents` file. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `Highlight` to their React component implementations.
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature). If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Code` (which is used to render [Markdown code blocks](./markdown-features-code-blocks.mdx)).
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper: If you want to register extra tag names (like the `<Highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
```js title="src/theme/MDXComponents.js" ```js title="src/theme/MDXComponents.js"
import React from 'react'; import React from 'react';
@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight';
export default { export default {
// Re-use the default mapping // Re-use the default mapping
...MDXComponents, ...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component! // Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `highlight` in MDX // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// highlight-next-line // highlight-next-line
highlight: Highlight, Highlight,
}; };
``` ```
And now, you can freely use `<highlight>` in every page, without writing the import statement: And now, you can freely use `<Highlight>` in every page, without writing the import statement:
```md ```md
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
``` ```
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
</BrowserWindow> </BrowserWindow>
``` ```
:::info :::warning
We use lower-case tag names like `highlight` to "pretend" that they are intrinsic elements, but you can use capitalized ones like `Highlight` as well. We use **upper-case** tag names like `Highlight` on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
::: :::

2
website/src/theme/MDXComponents.tsx
View file

@ -11,6 +11,6 @@ import TweetQuote from '@site/src/components/TweetQuote';
export default { export default {
...MDXComponents, ...MDXComponents,
highlight: Highlight, Highlight,
TweetQuote, TweetQuote,
}; };

28
website/versioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx
View file

@ -152,16 +152,16 @@ For example, given this MDX file:
- a - a
- list! - list!
And some <highlight>custom markup</highlight>... And some <Highlight>custom markup</Highlight>...
``` ```
It will be compiled to a React component containing `ul`, `li`, `p`, and `highlight` tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (`highlight` isn't even an intrinsic element: it needs an implementation!) It will be compiled to a React component containing `ul`, `li`, `p`, and `Highlight` elements. `Highlight` is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations. In Docusaurus, the MDX component scope is provided by the `@theme/MDXComponents` file. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `Highlight` to their React component implementations.
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature). If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Code` (which is used to render [Markdown code blocks](./markdown-features-code-blocks.mdx)).
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper: If you want to register extra tag names (like the `<Highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
```js title="src/theme/MDXComponents.js" ```js title="src/theme/MDXComponents.js"
import React from 'react'; import React from 'react';
@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight';
export default { export default {
// Re-use the default mapping // Re-use the default mapping
...MDXComponents, ...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component! // Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `highlight` in MDX // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// highlight-next-line // highlight-next-line
highlight: Highlight, Highlight,
}; };
``` ```
And now, you can freely use `<highlight>` in every page, without writing the import statement: And now, you can freely use `<Highlight>` in every page, without writing the import statement:
```md ```md
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
``` ```
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
</BrowserWindow> </BrowserWindow>
``` ```
:::info :::warning
We use lower-case tag names like `highlight` to "pretend" that they are intrinsic elements, but you can use capitalized ones like `Highlight` as well. We use **upper-case** tag names like `Highlight` on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
::: :::

28
website/versioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx
View file

@ -152,16 +152,16 @@ For example, given this MDX file:
- a - a
- list! - list!
And some <highlight>custom markup</highlight>... And some <Highlight>custom markup</Highlight>...
``` ```
It will be compiled to a React component containing `ul`, `li`, `p`, and `highlight` tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (`highlight` isn't even an intrinsic element: it needs an implementation!) It will be compiled to a React component containing `ul`, `li`, `p`, and `Highlight` elements. `Highlight` is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations. In Docusaurus, the MDX component scope is provided by the `@theme/MDXComponents` file. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `Highlight` to their React component implementations.
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature). If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Code` (which is used to render [Markdown code blocks](./markdown-features-code-blocks.mdx)).
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper: If you want to register extra tag names (like the `<Highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
```js title="src/theme/MDXComponents.js" ```js title="src/theme/MDXComponents.js"
import React from 'react'; import React from 'react';
@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight';
export default { export default {
// Re-use the default mapping // Re-use the default mapping
...MDXComponents, ...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component! // Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `highlight` in MDX // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// highlight-next-line // highlight-next-line
highlight: Highlight, Highlight,
}; };
``` ```
And now, you can freely use `<highlight>` in every page, without writing the import statement: And now, you can freely use `<Highlight>` in every page, without writing the import statement:
```md ```md
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
``` ```
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
</BrowserWindow> </BrowserWindow>
``` ```
:::info :::warning
We use lower-case tag names like `highlight` to "pretend" that they are intrinsic elements, but you can use capitalized ones like `Highlight` as well. We use **upper-case** tag names like `Highlight` on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
::: :::

28
website/versioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx
View file

@ -152,16 +152,16 @@ For example, given this MDX file:
- a - a
- list! - list!
And some <highlight>custom markup</highlight>... And some <Highlight>custom markup</Highlight>...
``` ```
It will be compiled to a React component containing `ul`, `li`, `p`, and `highlight` tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (`highlight` isn't even an intrinsic element: it needs an implementation!) It will be compiled to a React component containing `ul`, `li`, `p`, and `Highlight` elements. `Highlight` is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations. In Docusaurus, the MDX component scope is provided by the `@theme/MDXComponents` file. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `Highlight` to their React component implementations.
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature). If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Code` (which is used to render [Markdown code blocks](./markdown-features-code-blocks.mdx)).
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper: If you want to register extra tag names (like the `<Highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
```js title="src/theme/MDXComponents.js" ```js title="src/theme/MDXComponents.js"
import React from 'react'; import React from 'react';
@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight';
export default { export default {
// Re-use the default mapping // Re-use the default mapping
...MDXComponents, ...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component! // Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `highlight` in MDX // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// highlight-next-line // highlight-next-line
highlight: Highlight, Highlight,
}; };
``` ```
And now, you can freely use `<highlight>` in every page, without writing the import statement: And now, you can freely use `<Highlight>` in every page, without writing the import statement:
```md ```md
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
``` ```
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
</BrowserWindow> </BrowserWindow>
``` ```
:::info :::warning
We use lower-case tag names like `highlight` to "pretend" that they are intrinsic elements, but you can use capitalized ones like `Highlight` as well. We use **upper-case** tag names like `Highlight` on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
::: :::

28
website/versioned_docs/version-2.3.1/guides/markdown-features/markdown-features-react.mdx
View file

@ -152,16 +152,16 @@ For example, given this MDX file:
- a - a
- list! - list!
And some <highlight>custom markup</highlight>... And some <Highlight>custom markup</Highlight>...
``` ```
It will be compiled to a React component containing `ul`, `li`, `p`, and `highlight` tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (`highlight` isn't even an intrinsic element: it needs an implementation!) It will be compiled to a React component containing `ul`, `li`, `p`, and `Highlight` elements. `Highlight` is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations. In Docusaurus, the MDX component scope is provided by the `@theme/MDXComponents` file. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `Highlight` to their React component implementations.
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature). If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Code` (which is used to render [Markdown code blocks](./markdown-features-code-blocks.mdx)).
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper: If you want to register extra tag names (like the `<Highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
```js title="src/theme/MDXComponents.js" ```js title="src/theme/MDXComponents.js"
import React from 'react'; import React from 'react';
@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight';
export default { export default {
// Re-use the default mapping // Re-use the default mapping
...MDXComponents, ...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component! // Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `highlight` in MDX // `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// highlight-next-line // highlight-next-line
highlight: Highlight, Highlight,
}; };
``` ```
And now, you can freely use `<highlight>` in every page, without writing the import statement: And now, you can freely use `<Highlight>` in every page, without writing the import statement:
```md ```md
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
``` ```
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere! I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
</BrowserWindow> </BrowserWindow>
``` ```
:::info :::warning
We use lower-case tag names like `highlight` to "pretend" that they are intrinsic elements, but you can use capitalized ones like `Highlight` as well. We use **upper-case** tag names like `Highlight` on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
::: :::