Skip to main content
Version: 3.7.0

警告

除了基本的Markdown语法外，我们还有一种特殊的警告语法，通过用三个冒号包裹文本，后面跟着表示其类型的标签。

示例：

:::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`](#).

:::
http://localhost:3000
note

一些带有内容的Markdown syntax。查看这个api。

tip

一些带有内容的Markdown syntax。查看这个api。

info

一些带有内容的Markdown syntax。查看这个api。

warning

一些带有内容的Markdown syntax。查看这个api。

danger

一些带有内容的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:::

指定标题​

您还可以指定一个可选的标题。

:::note[Your Title **with** some _Markdown_ `syntax`!]

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

:::
http://localhost:3000
Your Title with some Markdown syntax!

一些内容带有一些Markdown syntax。

嵌套的警告​

警告可以嵌套。对于每个父警告级别，使用更多的冒号 :。

:::::info[Parent]

Parent content

::::danger[Child]

Child content

:::tip[Deep Child]

Deep child content

:::

::::

:::::
http://localhost:3000
Parent

父内容

子

子内容

深层子

深层子内容

使用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>Some information</p>
      </Admonition>
    </div>
  );
}

接受的类型与上述相同：note, tip, danger, info, warning。可选地，您可以通过传递一个JSX元素或字符串，或一个标题来指定一个图标：

MyReactPage.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>
http://localhost:3000
💡Did you know...

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

自定义警告​

有两种可能的自定义方式用于警告：解析和渲染。

自定义渲染行为​

你可以通过swizzling自定义每种警告类型的渲染方式。通常，你可以通过一个简单的包装器实现你的目标。例如，在下面的例子中，我们只替换了info警告的图标。

src/theme/Admonition.js
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键传递选项。

docusaurus.config.js
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：

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      'classic',
      {
        // ...
        docs: {
          admonitions: {
            keywords: ['my-custom-admonition'],
            extendDefaults: true,
          },
        },
      },
    ],
  ],
};

你可以通过创建以下文件为:::my-custom-admonition提供相应的React组件（不幸的是，由于它不是React组件文件，因此不可swizzlable）：

src/theme/Admonition/Types.js
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!

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

它工作了！