告示
除了基本的 Markdown 语法， 我们还有一种特殊的告示语法。它用 3 个连续的冒号包裹文本，然后紧跟着一个表示其类型的文本标签。
示例：
:::note
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::tip
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::info
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::warning
Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。
:::
:::danger
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
与 Prettier 一起使用
如果你在用 Prettier 格式化你的 Markdown 文件，Prettier 可能会把你的代码自动格式化成错误语法。 要避免这个问题，你可以在开始和结束的 ::: 周围空出一行。 这也是为什么我们这里的例子在内容两端都有空行。
<-- Prettier 不会动这个 -->
:::note
Hello world
:::
<!-- Prettier 会把这个 -->
:::note
Hello world
:::
<!-- 变成这个 -->
:::note[Hello world:::]
指定标题
你也可以为告示提供一个可选的标题。
:::note[Your Title **with** some _Markdown_ `syntax`!]
Some **content** with some _Markdown_ `syntax`.
:::
syntax!Some content with some Markdown syntax.
嵌套提示
告示可以嵌套。 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
你也可以在告示中使用 MDX！
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 中的用法
在非 Markdown 的文件里，你可以使用 @theme/Admonition 组件来达到相同的效果。
import Admonition from '@theme/Admonition';
export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>一些信息</p>
</Admonition>
</div>
);
}
The types that are accepted are the same as above: note, tip, danger, info, warning. 你也可以选择性地以 JSX 元素或者字符串的形式指定一个图标或者一个标题：
<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.
自定义告示
你可以对告示进行两类自定义：自定义解析和自定义渲染。
自定义渲染行为
You can customize how each individual admonition type is rendered through swizzling. 一般只需要一个简单的包装组件就可以达到想要的效果。 比如下面，我们针对 info 类的告示替换了图标。
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} />;
}
自定义解析行为
告示是通过 Remark 插件实现的。 这个插件被设计为可配置的。 要为某个特定的内容插件（文档、博客、页面等）配置相应的 Remark 插件，可以通过 admonitions 键传递对应的选项。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger'],
extendDefaults: true,
},
},
},
],
],
};
The plugin accepts the following options:
keywords：一组关键字，可以用作告示的类型。extendDefaults: Should the provided options (such askeywords) be merged into the existing defaults. Defaults totrue.
keyword 的内容会通过 type prop 传递给 Admonition 组件。
自定义告示组件的类型
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!