告示
除了基本的 Markdown 語法外，我們還有一個特殊的告示語法，方法是用一組 3 個冒號將文字包起來，後面跟著表示其類型的標籤。
範例
:::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 一起使用
如果您使用 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`.
:::
語法！一些使用 Markdown 語法 的內容。
巢狀告示
告示可以巢狀。為每個父告示級別使用更多冒號 :。
:::::info[Parent]
Parent content
::::danger[Child]
Child content
:::tip[Deep Child]
Deep child content
:::
::::
:::::
父內容
子內容
深層子內容
使用 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>
:::
- 蘋果
- 橘子
- 香蕉
在 JSX 中使用
在 Markdown 之外，您可以使用 @theme/Admonition 元件來獲得相同的輸出。
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 元素或字串來指定一個圖示，或指定一個標題
<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>
使用外掛為您的專案中最常用的 JSX 元素引入更短的語法。
自訂告示
告示有兩種自訂方式：解析 和 渲染。
自訂渲染行為
您可以通過 swizzling 自訂每個告示類型的渲染方式。您通常可以通過一個簡單的包裝器來實現您的目標。例如，在以下範例中，我們僅將圖示替換為 info 告示。
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 鍵傳遞選項。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger'],
extendDefaults: true,
},
},
},
],
],
};
該外掛接受以下選項
keywords：可用作告示類型的關鍵字陣列。extendDefaults：提供的選項（例如keywords）是否應合併到現有的默認值中。默認為true。
keyword 將作為 type prop 傳遞給 Admonition 元件。
自訂告示類型元件
默認情況下，主題不知道如何處理自訂告示關鍵字，例如 :::my-custom-admonition。您有責任將每個告示關鍵字映射到一個 React 元件，以便主題知道如何渲染它們。
如果您通過以下配置註冊了一個新的告示類型 my-custom-admonition
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
您可以通過創建以下檔案來為 :::my-custom-admonition 提供相應的 React 元件（遺憾的是，由於它不是 React 元件檔案，因此無法進行 swizzling）
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!
:::
我的標題
它有效！