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`](#).
:::
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écifier un titre
Vous pouvez également spécifier un titre facultatif.
:::note Votre Titre
Un peu de **contenu** avec la `syntaxe` _Markdown_.
:::
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>
:::
Utilisez les onglets dans les admonitions
- Apple
- Orange
- Banana
Utilisation dans 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, 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="Savez vous que ...">
<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>
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 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.
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.