Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slorber merged 1 commit into from
Mar 16, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 15 additions & 13 deletions website/docs/guides/markdown-features/markdown-features-react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,16 +152,16 @@ For example, given this MDX file:
- a
- 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"
import React from 'react';
Expand All @@ -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 <Highlight /> component!
// `Highlight` will receive all props that were passed to `highlight` in MDX
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// 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
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
<BrowserWindow>

I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

</BrowserWindow>
```

:::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.

:::

Expand Down
2 changes: 1 addition & 1 deletion website/src/theme/MDXComponents.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,6 @@ import TweetQuote from '@site/src/components/TweetQuote';

export default {
...MDXComponents,
highlight: Highlight,
Highlight,
TweetQuote,
};
28 changes: 15 additions & 13 deletions ...rsioned_docs/version-2.0.1/guides/markdown-features/markdown-features-react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,16 +152,16 @@ For example, given this MDX file:
- a
- 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"
import React from 'react';
Expand All @@ -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 <Highlight /> component!
// `Highlight` will receive all props that were passed to `highlight` in MDX
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// 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
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
<BrowserWindow>

I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

</BrowserWindow>
```

:::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.

:::

Expand Down
28 changes: 15 additions & 13 deletions ...rsioned_docs/version-2.1.0/guides/markdown-features/markdown-features-react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,16 +152,16 @@ For example, given this MDX file:
- a
- 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"
import React from 'react';
Expand All @@ -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 <Highlight /> component!
// `Highlight` will receive all props that were passed to `highlight` in MDX
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// 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
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
<BrowserWindow>

I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

</BrowserWindow>
```

:::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.

:::

Expand Down
28 changes: 15 additions & 13 deletions ...rsioned_docs/version-2.2.0/guides/markdown-features/markdown-features-react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,16 +152,16 @@ For example, given this MDX file:
- a
- 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"
import React from 'react';
Expand All @@ -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 <Highlight /> component!
// `Highlight` will receive all props that were passed to `highlight` in MDX
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
// 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
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
<BrowserWindow>

I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!

</BrowserWindow>
```

:::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.

:::

Expand Down
Loading