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

docs: multiple doc improvements (#6449)

Browse source
This commit is contained in:
Joshua Chen 2022-01-23 15:49:28 +08:00 • committed by GitHub
parent d0b4aaffed
commit 8140560332
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 84 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -24,14 +24,6 @@ While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the synta
:::
:::caution
MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018).
Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
:::
To define any custom component within an MDX file, you have to export it.
```jsx
@ -77,6 +69,26 @@ I can write **Markdown** alongside my _JSX_!
</BrowserWindow>
```
:::caution MDX is 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 -->
```jsx
/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>
```
This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
In addition, MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018). Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
:::
### Importing components
You can also import your own components defined in other files or third-party components installed via npm.
<!-- prettier-ignore -->
@ -91,18 +103,36 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
:::tip
The `@site` alias points to your website's directory, where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.md) and [translating](../../i18n/i18n-tutorial.md).
The `@site` alias points to your website's directory, usually where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.md) and [translating](../../i18n/i18n-tutorial.md).
:::
While declaring components within Markdown is very convenient for simple cases, it becomes hard to maintain because of limited editor support, risks of parsing errors, and low reusability. Use a separate `.js` file when your component involves complex JS logic:
```jsx title="src/components/Highlight.js"
export default function Highlight({children, color}) {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}
```
```md title="markdown-file.mdx"
import Highlight from '@site/src/components/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.
:::caution
Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
:::
### Markdown and JSX interoperability
Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.