提示框
除了基础的 Markdown 语法，我们还提供了一种特殊的提示框语法，即用一组三个冒号 ::: 将文本包裹起来，并紧跟一个表示其类型的标签。
示例：
:::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[你的标题**可以带**一些 _Markdown_ `语法`！]
一些带有一些 _Markdown_ `语法`的**内容**。
:::
语法！一些带有一些 Markdown 语法的内容。
嵌套提示框
提示框可以嵌套使用。每增加一个父级提示框层级，就增加一个冒号 :。
:::::info[Parent]
父级内容
::::danger[Child]
子级内容
:::tip[Deep Child]
深层子级内容
:::
::::
:::::
父级内容
子级内容
深层子级内容
在 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>
:::
- 苹果
- 橘子
- 香蕉
在 JSX 中使用
在 Markdown 文件之外，你可以使用 @theme/Admonition 组件来获得相同的输出效果。
import Admonition from '@theme/Admonition';
export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>一些信息</p>
</Admonition>
</div>
);
}
可接受的类型与前面相同：note、tip、danger、info、warning。你还可以选择性地通过传递一个 JSX 元素或一个字符串来指定图标，或者指定一个标题：
<Admonition type="tip" icon="💡" title="你知道吗...">
使用插件可以为你的项目中那些最常用的 JSX 元素引入更简洁的语法。
</Admonition>
使用插件可以为你的项目中那些最常用的 JSX 元素引入更简洁的语法。
自定义提示框
对于提示框，有两种类型的定制是可行的：解析（parsing）和渲染（rendering）。
自定义渲染行为
你可以通过 Swizzling 来定制每种提示框类型的渲染方式。通常，你只需通过一个简单的包装器（wrapper）就能实现目标。例如，在下面的例子中，我们只替换了 info 类型提示框的图标。
import React from 'react';
import Admonition from '@theme-original/Admonition';
import MyCustomNoteIcon from '@site/static/img/info.svg';
export default function AdmonitionWrapper(props) {
// 如果提示框类型不是 'info'，则使用自定义标题
if (props.type !== 'info') {
return <Admonition title="我的自定义提示框标题" {...props} />;
}
// 否则，只替换 'info' 类型的图标
return <Admonition icon={<MyCustomNoteIcon />} {...props} />;
}
自定义解析行为
提示框是通过一个 Remark 插件实现的。该插件被设计为可配置的。要为特定的内容插件（如 docs、blog、pages）定制 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 属性（prop）传递。
自定义提示框类型组件
默认情况下，主题不知道如何处理自 定义的提示框关键字，比如 :::my-custom-admonition。你需要负责将每个提示框关键字映射到一个 React 组件，以便主题知道如何渲染它们。
如果你通过以下配置注册了一个新的提示框类型 my-custom-admonition：
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
你可以通过创建以下文件来为 :::my-custom-admonition 提供相应的 React 组件（不幸的是，因为它不是一个标准的 React 组件文件，所以它不支持 swizzling）：
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-custom-admonition [我的标题]
它成功了！
:::