跳到主要内容
版本:Canary 🚧

告示

除了基本的 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 语法内容

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

你也可以在告示中使用 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>一些信息</p>
</Admonition>
</div>
);
}

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

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

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

自定义告示

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

自定义渲染行为

你可以通过 swizzle 自定义每种告示是如何被渲染的。 一般只需要一个简单的包装组件就可以达到想要的效果。 比如下面,我们针对 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
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
tag: ':::',
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
extendDefaults: true,
},
},
},
],
],
};

The plugin accepts the following options:

  • tag:包裹告示的标识。 默认为 :::
  • keywords:一组关键字,可以用作告示的类型。
  • extendDefaults: 提供的设置(如 keywords) 是否与合并到默认设置中. 默认值为 false

keyword 的内容会通过 type prop 传递给 Admonition 组件。

自定义告示组件的类型

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.

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

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

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;

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 自定义的告示

它可以用了!

:::
http://localhost:3000
自定义的告示

它可以用了!