Aller au contenu principal
Version : 2.x

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

Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).

:::

:::tip

Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).

:::

:::info

Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).

:::

:::caution

Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).

:::

:::danger

Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).

:::
http://localhost:3000
remarque

Un peu de contenu avec la syntaxe Markdown. Consultez cette api.

astuce

Un peu de contenu avec la syntaxe Markdown. Consultez cette api.

info

Un peu de contenu avec la syntaxe Markdown. Consultez cette api.

attention

Un peu de contenu avec la syntaxe Markdown. Consultez cette api.

danger

Un peu de contenu avec la syntaxe Markdown. Consultez cette api.

Utilisation avec Prettier​

Si vous utilisez Prettier pour formater vos fichiers Markdown, Prettier risque d'auto-formater votre code en syntaxe d'admonition invalide. 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 ne change pas ceci -->
:::note

Hello world

:::

<!-- Prettier change ceci -->
:::note
Hello world
:::

<!--en cela -->
::: note Hello world:::

SpĂ©cification d'un titre​

Vous pouvez également spécifier un titre facultatif.

:::note Votre titre

Un peu de **contenu** avec la `syntaxe` _Markdown_.

:::
http://localhost:3000
Votre titre

Un peu de contenu avec la syntaxe Markdown.

Admonitions avec MDX​

Vous pouvez Ă©galement utiliser MDX dans les admonitions !

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

:::tip

Utiliser les onglets dans les admonitions

<Tabs>
<TabItem value="apple" label="Apple">Ceci est une pomme 🍎</TabItem>
<TabItem value="orange" label="Orange">Ceci est une orange 🍊</TabItem>
<TabItem value="banana" label="Banana">Ceci est une banane 🍌</TabItem>
</Tabs>

:::
http://localhost:3000
astuce

Utilisez les onglets dans les admonitions

Ceci est une pomme 🍎

Utilisation en JSX​

En dehors de Markdown, vous pouvez utiliser le composant @theme/Admonition pour obtenir le mĂȘme rĂ©sultat.

MyReactPage.jsx
import Admonition from '@theme/Admonition';

export default function MyReactPage() {
return (
<div>
<Admonition type="info">
<p>Quelques informations</p>
</Admonition>
</div>
);
}

Les types qui sont acceptĂ©s sont les mĂȘmes que ci-dessus : 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 :

MyReactPage.jsx
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Utilisez des plugins pour introduire une syntaxe plus courte pour les éléments JSX les plus couramment utilisés
dans votre projet.
</p>
</Admonition>
http://localhost:3000
💡Did you know...

Utilisez des plugins pour introduire une syntaxe plus courte pour les éléments JSX les plus couramment utilisés dans votre projet.

Personnalisation des admonitions​

Il y a deux types de personnalisations possibles avec les admonitions : l'analyse et le rendu.

Personnalisation du comportement du rendu​

Vous pouvez personnaliser la façon dont chaque type d'admonition individuel est affiché via le swizzling. Vous pouvez souvent atteindre votre objectif grùce à un emballage simple. Par exemple, dans l'exemple suivant, nous permutons seulement l'icÎne pour les admonitions de type info.

src/theme/Admonition.js
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} />;
}

Personnalisation du comportement d'analyse​

Les Admonitions sont implĂ©mentĂ©es avec un plugin Remark. Le plugin est conçu pour ĂȘtre configurable. Pour personnaliser le plugin Remark pour un plugin de contenu spĂ©cifique (docs, blog, pages), passez les options Ă  travers la clĂ© admonitions.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
tag: ':::',
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
},
},
},
],
],
};

Le plugin accepte deux options :

  • tag : La balise qui entoure l'admonition. Par dĂ©faut, :::.
  • keywords : Un tableau de mots-clĂ©s qui peut ĂȘtre utilisĂ© comme type pour l'admonition. Notez que si vous remplacez ceci, les valeurs par dĂ©faut ne seront pas appliquĂ©es.

Le keyword sera passĂ© comme prop de type du composant Admonition. 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. Vous devrez gĂ©nĂ©ralement Ă©jecter le composant @theme/Admonition, afin de pouvoir rĂ©utiliser la mĂȘme infrastructure que les autres types.