提示
除了基本的 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`](#).
:::
:::warning
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
与 Prettier 结合使用
如果您使用 Prettier 格式化 Markdown 文件，Prettier 可能会将您的代码自动格式化为无效的提示语法。为了避免此问题，请在起始和结束指令周围添加空行。这也是我们在此处显示的所有示例在内容周围都带有空行的原因。
<!-- Prettier doesn't change this -->
:::note
Hello world
:::
<!-- Prettier changes this -->
:::note
Hello world
:::
<!-- to this -->
::: note Hello world:::
指定标题
您还可以指定一个可选的标题。
:::note[Your Title **with** some _Markdown_ `syntax`!]
Some **content** with some _Markdown_ `syntax`.
:::
语法！一些使用 内容 和一些 Markdown 语法。
嵌套提示
提示可以嵌套。对每个父提示级别使用更多冒号 :。
:::::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[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>
:::
- 苹果
- 橙子
- 香蕉
在 JSX 中使用
在 Markdown 之外，您可以使用 @theme/Admonition 组件来获得相同的输出。
import Admonition from '@theme/Admonition';
export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>Some information</p>
</Admonition>
</div>
);
}
接受的类型与上面相同：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>
使用插件为项目中最常用的 JSX 元素引入更简洁的语法。
自定义提示
提示可以进行两种自定义：解析 和 渲染。
自定义渲染行为
您可以通过 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,
},
},
},
],
],
};
该插件接受以下选项
keywords：可用于作为提示类型的关键字数组。extendDefaults：提供的选项（例如keywords）是否应合并到现有默认值中。默认为true。
keyword 将作为 Admonition 组件的 type 属性传递。
自定义提示类型组件
默认情况下，主题不知道如何处理自定义提示关键字，例如 :::my-custom-admonition。您有责任将每个提示关键字映射到一个 React 组件，以便主题知道如何渲染它们。
如果您通过以下配置注册了一个新的提示类型 my-custom-admonition
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
您可以通过创建以下文件为 :::my-custom-admonition 提供相应的 React 组件（不幸的是，由于它不是 React 组件文件，因此不可 swizzle）
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;
现在您可以在 Markdown 文件中使用新的提示关键字，它将使用您的自定义逻辑进行解析和渲染
:::my-custom-admonition[My Title]
It works!
:::
我的标题
它有效！