跳到主要内容
版本：2.3.1

告示

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

示例：

:::note

Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。

:::  

:::tip

Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。

:::  

:::info

Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。

:::  

:::caution

Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。

:::  

:::danger

Some **content** with _Markdown_ `syntax`. 看看[这个 `api`](#)。

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

Some content with Markdown syntax. 看看这个 api。

提示

Some content with Markdown syntax. 看看这个 api。

信息

Some content with Markdown syntax. 看看这个 api。

注意

Some content with Markdown syntax. 看看这个 api。

危险

Some content with Markdown syntax. 看看这个 api。

与 Prettier 一起使用​

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

<!-- Prettier doesn't change this -->
:::note

Hello world

:::  

<!-- Prettier changes this -->
:::note
Hello world
:::  

<!-- to this -->
::: note Hello world
:::

指定标题​

You may also specify an optional title.

:::note Your Title

Some **content** with _Markdown_ `syntax`.

:::
http://localhost:3000
Your Title

Some content with Markdown syntax.

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

:::
http://localhost:3000
提示

Use tabs in admonitions

This is an apple 🍎

JSX 中的用法​

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

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

export default function MyReactPage() {
  return (
    <div>
      <Admonition type="info">
        <p>一些信息</p>
      </Admonition>
    </div>
  );
}

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

MyReactPage.jsx
<Admonition type="tip" icon="💡" title="你知道吗……">
  <p>
    使用插件为你项目中最常用的 JSX 元素引入较短的语法。
  </p>
</Admonition>
http://localhost:3000
💡Did you know...

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 类的告示替换了图标。

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 组件。 如果你注册了默认值之外的类型，你就需要负责提供它们的实现，包括容器的样式、图标、默认标题文本等。 You would usually need to eject the @theme/Admonition component, so you could re-use the same infrastructure as the other types.