Skip to main content

Version: 3.6.1

告诫

¥Admonitions

除了基本的 Markdown 语法之外，我们还有一种特殊的警告语法，即用一组 3 个冒号封装文本，后跟一个表示其类型的标签。

¥In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.

示例：

¥Example:

:::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

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 一起使用

¥Usage with Prettier

如果你使用 Prettier 来格式化 Markdown 文件，Prettier 可能会将你的代码自动格式化为无效的警告语法。为了避免此问题，请在开始和结束指令周围添加空行。这也是为什么我们在这里展示的示例的内容周围都有空行。

¥If you use Prettier to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.

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

:::note

Hello world

:::

<!-- Prettier changes this -->

:::note

Hello world

:::

<!-- to this -->

::: note Hello world:::

指定标题

¥Specifying title

你还可以指定一个可选标题。

¥You may also specify an optional title.

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

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

:::

http://localhost:3000

Your Title with some Markdown syntax!

Some content with some Markdown syntax.

嵌套警告

¥Nested admonitions

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

¥Admonitions can be nested. Use more colons : for each parent admonition level.

:::::info[Parent]

Parent content

::::danger[Child]

Child content

:::tip[Deep Child]

Deep child content

:::

::::

:::::

http://localhost:3000

Parent

Parent content

Child

Child content

Deep Child

Deep child content

MDX 的警告

¥Admonitions with MDX

你也可以在警告中使用 MDX！

¥You can use MDX inside admonitions too!

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

Apple
Orange
Banana

This is an apple 🍎

在 JSX 中的用法

¥Usage in JSX

在 Markdown 之外，你可以使用 @theme/Admonition 组件来获得相同的输出。

¥Outside of Markdown, you can use the @theme/Admonition component to get the same output.

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 元素或字符串或标题来指定图标：

¥The types that are accepted are the same as above: note, tip, danger, info, warning. Optionally, you can specify an icon by passing a JSX element or a string, or a title:

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...

Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.

定制警告

¥Customizing admonitions

警告有两种可能的定制：解析和渲染。

¥There are two kinds of customizations possible with admonitions: parsing and rendering.

自定义渲染行为

¥Customizing rendering behavior

你可以自定义如何通过 swizzling 渲染每个单独的警告类型。你通常可以通过一个简单的封装器来实现你的目标。例如，在下面的示例中，我们仅替换 info 警告的图标。

¥You can customize how each individual admonition type is rendered through swizzling. You can often achieve your goal through a simple wrapper. For example, in the follow example, we swap out the icon for info admonitions only.

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} />;
}

自定义解析行为

¥Customizing parsing behavior

警告是通过 Remark 插件实现的。该插件被设计为可配置的。要为特定内容插件（文档、博客、页面）自定义 Remark 插件，请通过 admonitions 键传递选项。

¥Admonitions are implemented with a Remark plugin. The plugin is designed to be configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the admonitions key.

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          admonitions: {
            keywords: ['note', 'tip', 'info', 'warning', 'danger'],
            extendDefaults: true,
          },
        },
      },
    ],
  ],
};

该插件接受以下选项：

¥The plugin accepts the following options:

keywords：可用作警告类型的关键字数组。

¥keywords: An array of keywords that can be used as the type for the admonition.
extendDefaults：是否应将提供的选项（例如 keywords）合并到现有的默认值中。默认为 true。

¥extendDefaults: Should the provided options (such as keywords) be merged into the existing defaults. Defaults to true.

keyword 将作为 Admonition 组件的 type 属性传递。

¥The keyword will be passed as the type prop of the Admonition component.

自定义警告类型组件

¥Custom admonition type components

默认情况下，主题不知道如何处理自定义警告关键字（例如 :::my-custom-admonition）。你有责任将每个警告关键字映射到 React 组件，以便主题知道如何渲染它们。

¥By default, the theme doesn't know what do to with custom admonition keywords such as :::my-custom-admonition. It is your responsibility to map each admonition keyword to a React component so that the theme knows how to render them.

如果你通过以下配置注册了新的警告类型 my-custom-admonition：

¥If you registered a new admonition type my-custom-admonition via the following config:

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

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

¥You can provide the corresponding React component for :::my-custom-admonition by creating the following file (unfortunately, since it's not a React component file, it's not 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 文件中使用新的警告关键字，它将使用你的自定义逻辑进行解析和渲染：

¥Now you can use your new admonition keyword in a Markdown file, and it will be parsed and rendered with your custom logic:

:::my-custom-admonition[My Title]

It works!

:::

http://localhost:3000

My Title

It works!

与 Prettier 一起使用
指定标题
嵌套警告
MDX 的警告
在 JSX 中的用法
定制警告