diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 0327c1e16023..9768159642e8 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -152,16 +152,16 @@ For example, given this MDX file: - a - list! -And some custom markup... +And some custom markup... ``` -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 [``](./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 `` 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 `` 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" import React from 'react'; @@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight'; export default { // Re-use the default mapping ...MDXComponents, - // Map the "highlight" tag to our component! - // `Highlight` will receive all props that were passed to `highlight` in MDX + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX // highlight-next-line - highlight: Highlight, + Highlight, }; ``` -And now, you can freely use `` in every page, without writing the import statement: +And now, you can freely use `` in every page, without writing the import statement: ```md -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` ```mdx-code-block -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` -:::info +:::warning + +We use **upper-case** tag names like `Highlight` on purpose. -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. +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. ::: diff --git a/website/src/theme/MDXComponents.tsx b/website/src/theme/MDXComponents.tsx index 079cec7487ec..d2fd0c128232 100644 --- a/website/src/theme/MDXComponents.tsx +++ b/website/src/theme/MDXComponents.tsx @@ -11,6 +11,6 @@ import TweetQuote from '@site/src/components/TweetQuote'; export default { ...MDXComponents, - highlight: Highlight, + Highlight, TweetQuote, }; diff --git a/website/versioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx index a8d76f1067e9..5bd883980e72 100644 --- a/website/versioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx +++ b/website/versioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx @@ -152,16 +152,16 @@ For example, given this MDX file: - a - list! -And some custom markup... +And some custom markup... ``` -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 [``](./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 `` 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 `` 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" import React from 'react'; @@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight'; export default { // Re-use the default mapping ...MDXComponents, - // Map the "highlight" tag to our component! - // `Highlight` will receive all props that were passed to `highlight` in MDX + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX // highlight-next-line - highlight: Highlight, + Highlight, }; ``` -And now, you can freely use `` in every page, without writing the import statement: +And now, you can freely use `` in every page, without writing the import statement: ```md -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` ```mdx-code-block -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` -:::info +:::warning + +We use **upper-case** tag names like `Highlight` on purpose. -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. +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. ::: diff --git a/website/versioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx index a8d76f1067e9..5bd883980e72 100644 --- a/website/versioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx +++ b/website/versioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx @@ -152,16 +152,16 @@ For example, given this MDX file: - a - list! -And some custom markup... +And some custom markup... ``` -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 [``](./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 `` 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 `` 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" import React from 'react'; @@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight'; export default { // Re-use the default mapping ...MDXComponents, - // Map the "highlight" tag to our component! - // `Highlight` will receive all props that were passed to `highlight` in MDX + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX // highlight-next-line - highlight: Highlight, + Highlight, }; ``` -And now, you can freely use `` in every page, without writing the import statement: +And now, you can freely use `` in every page, without writing the import statement: ```md -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` ```mdx-code-block -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` -:::info +:::warning + +We use **upper-case** tag names like `Highlight` on purpose. -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. +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. ::: diff --git a/website/versioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx index a8d76f1067e9..5bd883980e72 100644 --- a/website/versioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx +++ b/website/versioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx @@ -152,16 +152,16 @@ For example, given this MDX file: - a - list! -And some custom markup... +And some custom markup... ``` -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 [``](./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 `` 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 `` 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" import React from 'react'; @@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight'; export default { // Re-use the default mapping ...MDXComponents, - // Map the "highlight" tag to our component! - // `Highlight` will receive all props that were passed to `highlight` in MDX + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX // highlight-next-line - highlight: Highlight, + Highlight, }; ``` -And now, you can freely use `` in every page, without writing the import statement: +And now, you can freely use `` in every page, without writing the import statement: ```md -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` ```mdx-code-block -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` -:::info +:::warning + +We use **upper-case** tag names like `Highlight` on purpose. -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. +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. ::: diff --git a/website/versioned_docs/version-2.3.1/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.3.1/guides/markdown-features/markdown-features-react.mdx index a8d76f1067e9..5bd883980e72 100644 --- a/website/versioned_docs/version-2.3.1/guides/markdown-features/markdown-features-react.mdx +++ b/website/versioned_docs/version-2.3.1/guides/markdown-features/markdown-features-react.mdx @@ -152,16 +152,16 @@ For example, given this MDX file: - a - list! -And some custom markup... +And some custom markup... ``` -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 [``](./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 `` 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 `` 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" import React from 'react'; @@ -173,30 +173,32 @@ import Highlight from '@site/src/components/Highlight'; export default { // Re-use the default mapping ...MDXComponents, - // Map the "highlight" tag to our component! - // `Highlight` will receive all props that were passed to `highlight` in MDX + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX // highlight-next-line - highlight: Highlight, + Highlight, }; ``` -And now, you can freely use `` in every page, without writing the import statement: +And now, you can freely use `` in every page, without writing the import statement: ```md -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` ```mdx-code-block -I can conveniently use Docusaurus green everywhere! +I can conveniently use Docusaurus green everywhere! ``` -:::info +:::warning + +We use **upper-case** tag names like `Highlight` on purpose. -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. +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. :::