アドモニッション
基本的な 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 要素の短い構文を導入します。
アドモニッションのカスタマイズ
アドモニッションでは、**解析** と **レンダリング** の 2 種類のカスタマイズが可能です。
レンダリング動作のカスタマイズ
スウィズリング を介して、個々のアドモニッションタイプがどのようにレンダリングされるかをカスタマイズできます。多くの場合、単純なラッパーで目標を達成できます。たとえば、次の例では、`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` は `Admonition` コンポーネントの `type` プロパティとして渡されます。
カスタムアドモニッションタイプコンポーネント
デフォルトでは、テーマは `:::my-custom-admonition` などのカスタムアドモニッションキーワードをどう処理すればいいのかわかりません。テーマがそれらをどのようにレンダリングするかを知るように、各アドモニッションキーワードを React コンポーネントにマッピングするのはあなたの責任です。
次の設定を介して新しいアドモニッションタイプ `my-custom-admonition` を登録した場合
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
次のファイルを作成することにより、 `:::my-custom-admonition` に対応する React コンポーネントを提供できます（残念ながら、React コンポーネントファイルではないため、スウィズルできません）
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!
:::
マイタイトル
動作します！