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`](#).
:::
:::warning
Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).
:::
:::danger
Un peu de **contenu** avec la `syntaxe` _Markdown_. Consultez [cette `api`](#).
:::
Un peu de contenu avec la syntaxe
Markdown. Consultez cette api
.
Un peu de contenu avec la syntaxe
Markdown. Consultez cette api
.
Un peu de contenu avec la syntaxe
Markdown. Consultez cette api
.
Un peu de contenu avec la syntaxe
Markdown. Consultez cette api
.
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 **avec** avec un peu de `syntaxe` _Markdown_Â !]
Du **contenu** avec un peu de `syntaxe` _Markdown_.
:::
syntaxe
Markdown !Du contenu avec un peu de syntaxe
Markdown.
Admonitions imbriquĂ©esâ
Les admonitions peuvent ĂȘtre imbriquĂ©es. Utilisez plus de deux points :
pour chaque niveau d'admonition parent.
:::::info[Parent]
Contenu du parent
::::danger[Fils]
Contenu du fils
:::tip[Petit-fils]
Contenu du petit-fils
:::
::::
:::::
Contenu du parent
Contenu du fils
Contenu du petit-fils
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>
:::
- Apple
- Orange
- Banana
Utilisation en JSXâ
En dehors de Markdown, vous pouvez utiliser le composant @theme/Admonition
pour obtenir le mĂȘme rĂ©sultat.
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
, warning
. 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...">
Utilisez des plugins pour introduire une syntaxe plus courte pour les éléments JSX les plus couramment utilisés
dans votre projet.
</Admonition>
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
.
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="Mon titre d'admonition personnalisé" {...props} />;
}
return <Admonition icon={<MyCustomNoteIcon />} {...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
.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger'],
extendDefaults: true,
},
},
},
],
],
};
Le plugin accepte les options suivantes :
keywords
 : Un tableau de mots-clĂ©s qui peut ĂȘtre utilisĂ© comme type pour l'admonition.extendDefaults
 : Est-ce que les options fournies (commekeywords
) doivent ĂȘtre fusionnĂ©es avec les valeurs par dĂ©faut existantes. Par dĂ©faut Ătrue
.
Le keyword
sera passé comme prop de type
du composant Admonition
.
Composants de type d'admonition personnalisĂ©sâ
Par défaut, le thÚme ne sait pas quoi faire avec les mots-clés d'admonition personnalisés tels que :::my-custom-admonition
. Il vous appartient de faire correspondre chaque mot-clé d'admonition à un composant React afin que le thÚme sache comment en assurer le rendu.
Si vous avez enregistré un nouveau type d'admonition my-custom-admonition
via la configuration suivante :
export default {
// ...
presets: [
[
'classic',
{
// ...
docs: {
admonitions: {
keywords: ['my-custom-admonition'],
extendDefaults: true,
},
},
},
],
],
};
Vous pouvez fournir le composant React correspondant pour :::my-custom-admonition
en créant le fichier suivant (malheureusement, comme ce n'est pas un fichier de composant React, ce n'est pas swizzlable) :
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,
// Ajoutez ici tous vos types d'admonitions personnalisées...
// Vous pouvez également écraser les valeurs par défaut si vous le souhaitez
'my-custom-admonition': MyCustomAdmonition,
};
export default AdmonitionTypes;
Vous pouvez maintenant utiliser votre nouveau mot clé d'admonition dans un fichier Markdown, qui sera analysé et rendu avec votre logique personnalisée :
:::my-custom-admonition[Mon Titre]
Ăa fonctionne !
:::
My Titre
Ăa fonctionne !