Admonitions
En plus de la syntaxe Markdown de base, nous disposons d'une syntaxe spéciale pour les admonitions, qui consiste à entourer le texte d'un ensemble de 3 deux-points, suivi d'une étiquette indiquant son type.
Exemple :
:::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`](#).
:::
:::caution
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
Usage with Prettier
If you use Prettier to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. Pour éviter ce problème, ajoutez des lignes vides autour des directives de début et de fin. C'est également la raison pour laquelle les exemples que nous présentons ici comportent tous des lignes vides autour du contenu.
<!-- Prettier doesn't change this -->
:::note
Hello world
:::
<!-- Prettier changes this -->
:::note
Hello world
:::
<!-- to this -->
::: note Hello world:::
Specifying title
Vous pouvez également spécifier un titre facultatif.
:::note Your Title
Some **content** with _Markdown_ `syntax`.
:::
Some content with Markdown syntax
.
Admonitions with MDX
Vous pouvez également utiliser MDX dans les admonitions !
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>
:::
- Apple
- Orange
- Banana
Usage in JSX
Outside of Markdown, you can use the @theme/Admonition
component to get the same output.
import Admonition from '@theme/Admonition';
export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>Some information</p>
</Admonition>
</div>
);
}
The types that are accepted are the same as above: note
, tip
, danger
, info
, caution
. Optionnellement, vous pouvez spécifier une icône en passant un élément JSX ou une chaîne, ou un titre :
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Use plugins to introduce shorter syntax for the most commonly used JSX
elements in your project.
</p>
</Admonition>
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
You can customize how each individual admonition type is rendered through swizzling. Vous pouvez souvent atteindre votre objectif grâce à un emballage simple. For example, in the follow example, we swap out the icon for info
admonitions only.
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} />;
}
Customizing parsing behavior
Admonitions are implemented with a Remark plugin. Le plugin est conçu pour être configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the admonitions
key.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
tag: ':::',
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
},
},
},
],
],
};
Le plugin accepte deux options :
tag
: The tag that encloses the admonition. Defaults to:::
.keywords
: An array of keywords that can be used as the type for the admonition. Notez que si vous remplacez ceci, les valeurs par défaut ne seront pas appliquées.
The keyword
will be passed as the type
prop of the Admonition
component. Si vous enregistrez d'autres types que ceux proposés par défaut, vous devez également fournir leur implémentation, notamment le style du conteneur, son icône, le texte du titre par défaut, etc. You would usually need to eject the @theme/Admonition
component, so you could re-use the same infrastructure as the other types.