告示
除了基本的 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`](#)。
:::
与 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`.
:::
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>
:::
Use tabs in admonitions
- Apple
- Orange
- Banana
JSX 中的用法
在非 Markdown 的文件里,你可以使用 @theme/Admonition
组件来达到相同的效果。
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 元素或者字符串的形式指定一个图标或者一个标题:
<Admonition type="tip" icon="💡" title="你知道吗……">
<p>
使用插件为你项目中最常用的 JSX 元素引入较短的语法。
</p>
</Admonition>
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
类的告示替换了图标。
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
键传递对应的选项。
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.