警告和标注
除了基本的 Markdown 语法，我们还有一种特殊的警告/标注语法，通过用三个冒号包裹文本，后跟一个表示其类型的标签。
示例：
:::note
一些带有 _Markdown_ `语法` 的 **内容**。查看 [这个 `api`](#)。
:::
:::tip
一些带有 _Markdown_ `语法` 的 **内容**。查看 [这个 `api`](#)。
:::
:::info
一些带有 _Markdown_ `语法` 的 **内容**。查看 [这个 `api`](#)。
:::
:::warning
一些带有 _Markdown_ `语法` 的 **内容**。查看 [这个 `api`](#)。
:::
:::danger
一些带有 _Markdown_ `语法` 的 **内容**。查看 [这个 `api`](#)。
:::
与 Prettier 一起使用
如果您使用 Prettier 格式化 Markdown 文件，Prettier 可能会自动格式化您的代码为无效的警告/标注语法。为避免此问题，请在起始和结束指令周围添加空行。这也是为什么我们展示的示例都在内容周围有空行。
<!-- Prettier 不会更改这个 -->
:::note
你好世界
:::
<!-- Prettier 会更改这个 -->
:::note
你好世界
:::
<!-- 变成这样 -->
::: note 你好世界:::
指定标题
您还可以指定一个可选的标题。
:::note[您的标题 **带有** 一些 _Markdown_ `语法`！]
一些带有一些 _Markdown_ `语法` 的 **内容**。
:::
语法！一些带有一些 Markdown 语法 的 内容。
嵌套警告/标注
警告/标注可以嵌套。对于每个父警告/标注级别使用更多的冒号 : 。
:::::info[父级]
父级内容
::::danger[子级]
子级内容
:::tip[深层子级]
深层子级内容
:::
::::
:::::
父级内容
子级内容
深层子级内容
使用 MDX 的警告/标注
您也可以在警告/标注中使用 MDX！
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::tip[在警告/标注中使用选项卡]
<Tabs>
<TabItem value="apple" label="苹果">这是一个苹果 🍎</TabItem>
<TabItem value="orange" label="橙子">这是一个橙子 🍊</TabItem>
<TabItem value="banana" label="香蕉">这是一个香蕉 🍌</TabItem>
</Tabs>
:::
- 苹果
- 橙子
- 香蕉
Usage in JSX
Outside of Markdown, you can use the @theme/Admonition component to get the same output.
import Admonition from '@theme/Admonition';
export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>Some information</p>
</Admonition>
</div>
);
}
The types that are accepted are the same as above: note, tip, danger, info, warning. Optionally, you can specify an icon by passing a JSX element or a string, or a title:
<Admonition type="tip" icon="💡" title="Did you know...">
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</Admonition>
Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.
Customizing admonitions
There are two kinds of customizations possible with admonitions: parsing and rendering.
Customizing rendering behavior
You can customize how each individual admonition type is rendered through swizzling. You can often achieve your goal through a simple wrapper. For example, in the follow example, we swap out the icon for info admonitions only.
import React from 'react';
import Admonition from '@theme-original/Admonition';
import MyCustomNoteIcon from '@site/static/img/info.svg';
export default function AdmonitionWrapper(props) {
if (props.type !== 'info') {
return <Admonition title="My Custom Admonition Title" {...props} />;
}
return <Admonition icon={<MyCustomNoteIcon />} {...props} />;
}
Customizing parsing behavior
Admonitions are implemented with a Remark plugin. The plugin is designed to be configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the admonitions key.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger'],
extendDefaults: true,
},
},
},
],
],
};
The plugin accepts the following options:
keywords: An array of keywords that can be used as the type for the admonition.extendDefaults: Should the provided options (such askeywords) be merged into the existing defaults. Defaults totrue.
The keyword will be passed as the type prop of the Admonition component.
Custom admonition type components
By default, the theme doesn't know what do to with custom admonition keywords such as :::my-custom-admonition. It is your responsibility to map each admonition keyword to a React component so that the theme knows how to render them.
If you registered a new admonition type my-custom-admonition via the following config:
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
You can provide the corresponding React component for :::my-custom-admonition by creating the following file (unfortunately, since it's not a React component file, it's not swizzlable):
import React from 'react';
import DefaultAdmonitionTypes from '@theme-original/Admonition/Types';
function MyCustomAdmonition(props) {
return (
<div style={{border: 'solid red', padding: 10}}>
<h5 style={{color: 'blue', fontSize: 30}}>{props.title}</h5>
<div>{props.children}</div>
</div>
);
}
const AdmonitionTypes = {
...DefaultAdmonitionTypes,
// Add all your custom admonition types here...
// You can also override the default ones if you want
'my-custom-admonition': MyCustomAdmonition,
};
export default AdmonitionTypes;
Now you can use your new admonition keyword in a Markdown file, and it will be parsed and rendered with your custom logic:
:::my-custom-admonition[My Title]
It works!
:::
My Title
It works!