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`](#).

:::

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[Your Title **with** some _Markdown_ `syntax`!]

Some **content** with some _Markdown_ `syntax`.

:::

http://localhost:3000

Your Title with some Markdown syntax!

Some content with some Markdown syntax.

Nested admonitions

Les admonitions peuvent être imbriquées. Use more colons : for each parent admonition level.

:::::info[Parent]

Contenu du parent

::::danger[Fils]

Contenu du fils

:::tip[Petit-fils]

Contenu du petit-fils

:::

::::

:::::

http://localhost:3000

Parent

Parent content

Child

Child content

Deep Child

Deep child content

Admonitions avec 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>

:::

http://localhost:3000

Use tabs in admonitions

Apple

This is an apple 🍎

Orange

This is an orange 🍊

Banana

This is a banana 🍌

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, warning. 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...">
  Use plugins to introduce shorter syntax for the most commonly used JSX
  elements in your project.
</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 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} />;
}

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

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: Should the provided options (such as keywords) be merged into the existing defaults. Defaults to true.

Le keyword sera passé comme prop de type du composant Admonition.

Custom admonition type components

By default, the theme doesn't know what do to with custom admonition keywords such as :::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.

If you registered a new admonition type my-custom-admonition via the following config:

docusaurus.config.js

export default {
  // ...
  presets: [
    [
      'classic',
      {
        // ...
        docs: {
          admonitions: {
            keywords: ['my-custom-admonition'],
            extendDefaults: true,
          },
        },
      },
    ],
  ],
};

You can provide the corresponding React component for :::my-custom-admonition by creating the following file (unfortunately, since it's not a React component file, it's not swizzlable):

src/theme/Admonition/Types.js

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;

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[My Title]

It works!

:::

http://localhost:3000

My Title

It works!