跳到主要内容
版本:2.0.0

告示

除了基本的 Markdown 语法, 我们还有一种特殊的告示语法。它用 3 个连续的冒号包裹文本,然后紧跟着一个表示其类型的文本标签。

示例:

:::note

一些包含 _Markdown_ `语法`**内容**。 看看[这个 `api`](#)

:::

:::tip

一些包含 _Markdown_ `语法`**内容**。 看看[这个 `api`](#)

:::

:::info

一些包含 _Markdown_ `语法`**内容**。 看看[这个 `api`](#)

:::

:::caution

一些包含 _Markdown_ `语法`**内容**。 看看[这个 `api`](#)

:::

:::danger

一些包含 _Markdown_ `语法`**内容**。 看看[这个 `api`](#)

:::
http://localhost:3000
备注

一些包含 Markdown 语法内容。 看看这个 api

提示

一些包含 Markdown 语法内容。 看看这个 api

信息

一些包含 Markdown 语法内容。 看看这个 api

注意

一些包含 Markdown 语法内容。 看看这个 api

危险

一些包含 Markdown 语法内容。 看看这个 api

与 Prettier 一起使用

如果你在用 Prettier 格式化你的 Markdown 文件,Prettier 可能会把你的代码自动格式化成错误语法。 要避免这个问题,你可以在开始和结束的 ::: 周围空出一行。 这也是为什么我们这里的例子在内容两端都有空行。

<-- Prettier 不会动这个 -->
:::note

Hello world

:::

<!-- Prettier 会把这个 -->
:::note
Hello world
:::

<!-- 变成这个 -->
:::note Hello world:::

指定标题

你也可以为告示提供一个可选的标题。

:::note 你的标题

一些包含 _Markdown_ `语法`**内容**

:::
http://localhost:3000
你的标题

一些包含 Markdown 语法内容

在告示中使用 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>

:::
http://localhost:3000
在告示中使用选项卡
这是个苹果 🍎

JSX 中的用法

在非 Markdown 的文件里,你可以使用 @theme/Admonition 组件来达到相同的效果。

MyReactPage.jsx
import Admonition from '@theme/Admonition';

export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>Some information</p>
</Admonition>
</div>
);
}

它接受的 type prop 和上文一致:notetipdangerinfocaution。 你也可以选择性地以 JSX 元素或者字符串的形式指定一个图标或者一个标题:

MyReactPage.jsx
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</p>
</Admonition>
http://localhost:3000
💡你知道吗……

使用插件为你项目中最常用的 JSX 元素引入较短的语法。

自定义告示

你可以对告示进行两类自定义:自定义解析和自定义渲染

自定义渲染行为

你可以通过 swizzle 自定义每种告示是如何被渲染的。 一般只需要一个简单的包装组件就可以达到想要的效果。 比如下面,我们针对 info 类的告示替换了图标。

src/theme/Admonition.js
import React from 'react';
import Admonition from '@theme-original/Admonition';
import MyIcon from '@site/static/img/info.svg';

export default function AdmonitionWrapper(props) {
if (props.type !== 'info') {
return <Admonition {...props} />;
}
return <Admonition icon={<MyIcon />} {...props} />;
}

自定义解析行为

告示是通过 Remark 插件实现的。 这个插件被设计为可配置的。 要为某个特定的内容插件(文档、博客、页面等)配置相应的 Remark 插件,可以通过 admonitions 键传递对应的选项。

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
tag: ':::',
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
},
},
},
],
],
};

插件接受两个选项:

  • tag:包裹告示的标识。 默认为 :::
  • keywords:一组关键字,可以用作告示的类型。 请注意,如果你覆盖了这个选项,就不会应用默认值。

keyword 的内容会通过 type prop 传递给 Admonition 组件。 如果你注册了默认值之外的类型,你就需要负责提供它们的实现,包括容器的样式、图标、默认标题文本等。 你一般需要弹出 @theme/Admonition 组件,这样才能复用其他告示类型的代码。