告示
除了基本的 Markdown 语法， 我们还有一种特殊的告示语法。它用 3 个连续的冒号包裹文本，然后紧跟着一个表示其类型的文本标签。
示例：
:::note
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::tip
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::info
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `api`](#)。
:::
:::warning
一些包含 _Markdown_ `语法` 的 **内容**。 看看[这个 `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.
嵌套告示
告示可以嵌套。 对每个父级的告示，冒号 : 的数量递增。
:::::info[Parent]
Parent content
::::danger[Child]
Child content
:::tip[Deep Child]
Deep child content
:::
::::
:::::
父级内容
子级内容
更深的子级内容
在告示中使用 MDX
你也可以在告示中使用 MDX！
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::tip[在告示中使用选项卡]
<Tabs>
<TabItem value="apple" label="Apple">这是苹果 🍎</TabItem>
<TabItem value="orange" label="Orange">这是橙子 🍊</TabItem>
<TabItem value="banana" label="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.
自定义告示
你可以对告示进行两类自定义：自定义解析和自定义渲染。
自定义渲染行为
你可以通过 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：是否将提供的选项（例如keywords）合并到现有的默认值中。 默认值为true。
keyword 的内容会通过 type prop 传递给 Admonition 组件。
自定义告示组件的类型
在默认情况下，主题并不知道该如何显示自定义关键字（如 :::my-custom-admonition）的告示。 你需要把每个告示关键字映射到 React 组件，这样主题就知道如何显示它们了。
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,
// 在这里添加自定义告示类型……
// 如果你需要，也可以覆盖默认的关键字
'my-custom-admonition': MyCustomAdmonition,
};
export default AdmonitionTypes;
现在你可以在 Markdown 文件中使用你的新告示关键字，它将被解析并按照你的自定义逻辑渲染出来：
:::my-custom-admonition[My Title]
It works!
:::
My Title
It works!