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

docs: document MDXComponents scope (#7503)

Browse source 
* docs: document MDXComponents scope

* address reviews

* add info
This commit is contained in:
Joshua Chen 2022-05-26 21:50:50 +08:00 • committed by GitHub
parent 06a37112bb
commit bac292d84b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 110 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -24,7 +24,11 @@ While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the synta
::: :::
To define any custom component within an MDX file, you have to export it. Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
### Exporting components {#exporting-components}
To define any custom component within an MDX file, you have to export it: only paragraphs that start with `export` will be parsed as components instead of prose.
```jsx ```jsx
export const Highlight = ({children, color}) => ( export const Highlight = ({children, color}) => (
@ -133,7 +137,69 @@ import Highlight from '@site/src/components/Highlight';
<Highlight color="#25c2a0">Docusaurus green</Highlight> <Highlight color="#25c2a0">Docusaurus green</Highlight>
``` ```
Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. :::tip
If you use the same component across a lot of files, you don't need to import it everywhere—consider adding it to the global scope. [See below](#mdx-component-scope)
:::
### MDX component scope {#mdx-component-scope}
Apart from [importing a component](#importing-components) and [exporting a component](#exporting-components), a third way to use a component in MDX is to **register it to the global scope**, which will make it automatically available in every MDX file, without any import statements.
For example, given this MDX file:
```md
- a
- list!
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!)
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.
If you [swizzle](../../swizzling.md) 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 want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.md#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';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
// highlight-next-line
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
// highlight-next-line
highlight: Highlight,
};
```
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!
```
```mdx-code-block
<BrowserWindow>
I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
</BrowserWindow>
```
:::info
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.
:::
### Markdown and JSX interoperability {#markdown-and-jsx-interoperability} ### Markdown and JSX interoperability {#markdown-and-jsx-interoperability}

28
website/src/components/Highlight.tsx Normal file
View file

@ -0,0 +1,28 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import React, {type ReactNode} from 'react';
export default function Highlight({
children,
color,
}: {
children: ReactNode;
color: string;
}): JSX.Element {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}

14
website/src/theme/MDXComponents.tsx Normal file
View file

@ -0,0 +1,14 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';
export default {
...MDXComponents,
highlight: Highlight,
};