警告
除了基本的 Markdown 语法之外，我们还有一个特殊的警告语法，即用一组 3 个冒号包裹文本，后面跟着一个表示其类型的标签。
例子:
:::note
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::tip
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::info
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::caution
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
与 Prettier 一起使用
If you use Prettier to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
<!-- Prettier doesn't change this -->
:::note
Hello world
:::
<!-- Prettier changes this -->
:::note
Hello world
:::
<!-- to this -->
::: note Hello world:::
指定标题
You may also specify an optional title.
:::note[Your Title **with** some _Markdown_ `syntax`!]
Some **content** with some _Markdown_ `syntax`.
:::
syntax!Some content with some Markdown syntax.
嵌套的警告
Admonitions can be nested. Use more colons : for each parent admonition level.
:::::info[Parent]
Parent content
::::danger[Child]
Child content
:::tip[Deep Child]
Deep child content
:::
::::
:::::
Parent content
Child content
Deep child content
MDX 的警告
You can use MDX inside admonitions too!
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::tip[Use tabs in admonitions]
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
</Tabs>
:::
- Apple
- Orange
- Banana
在 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, caution. 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.
自定义警告
There are two kinds of customizations possible with admonitions: parsing and rendering.
自定义呈现行为
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} />;
}
自定义解析行为
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.
module.exports = {
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
admonitions: {
keywords: ["note", "tip", "info", "caution", "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.
自定义警告类型组件
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:
module.exports = {
// ...
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!