Aller au contenu principal
Version : 2.0.1

Entêtes et table des matières

Entêtes Markdown

Vous pouvez utiliser les entêtes Markdown habituels.

## Titre de niveau 2

### Titre de niveau 3

#### Titre de niveau 4

Chaque entête Markdown apparaitra comme une entrée dans la table des matières.

ID des entêtes

Chaque entête a un ID qui peut être généré automatiquement ou explicitement spécifié. Les ID d'entête vous permettent de faire un lien vers un titre spécifique du document en Markdown ou JSX :

[link](#heading-id)
<Link to="#heading-id">link</Link>

Par défaut, Docusaurus générera des ID d'entête pour vous, en fonction du texte du titre. Par exemple, ### Hello World aura l'ID hello-world.

Les ID générés ont quelques limitations :

  • L'ID pourrait ne pas être correct
  • Vous pouvez modifier ou traduire le texte sans mettre à jour l'ID existant

Une syntaxe spéciale de Markdown vous permet de définir un id d'entête explicite:

### Hello World {#my-explicit-id}
astuce

Use the write-heading-ids CLI command to add explicit IDs to all your Markdown documents.

Éviter les collisions d'ID

Les ID d'entête générés sont garantis comme étant uniques sur chaque page, mais si vous utilisez des ID personnalisés, assurez-vous que chacun d'entre eux n'apparaît qu'une seule fois sur chaque page, sinon il y aura deux éléments DOM avec le même ID, ce qui n'est pas une sémantique HTML valide et entraînera l'impossibilité de lier une entête.

Niveau d'entête de la table des matières

Chaque document Markdown affiche une table des matières du contenu en haut à droite. Par défaut, cette table n'affiche que les titres h2 et h3, ce qui devrait être suffisant pour une vue d'ensemble de la structure des pages. Si vous avez besoin de modifier la plage des titres affichés, vous pouvez personnaliser le niveau minimum et maximum des titres - soit par page, soit globalement.

Pour définir le niveau de l'entête d'une page particulière, utilisez les toc_min_heading_level et toc_max_heading_level du frontmatter.

myDoc.md
---
# Affiche les entêtes de h2 à h5
toc_min_heading_level: 2
toc_max_heading_level: 5
---

To set the heading level for all pages, use the themeConfig.tableOfContents option.

docusaurus.config.js
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};

Si vous avez défini les options de manière globale, vous pouvez toujours les remplacer localement par le frontmatter.

remarque

L'option themeConfig s'appliquera à toutes les tables de matières du site, y compris la table de matières en ligne, mais les options du frontmatter n'affectent que la table de matières en haut à droite. Vous devez utiliser les props minHeadingLevel et maxHeadingLevel pour personnaliser chaque composant <TOCInline />.

Table des matières en ligne

Il est également possible d'afficher une table des matières en ligne directement à l'intérieur d'un document Markdown, grâce à MDX.

La variable toc est disponible dans n'importe quel document MDX et contient toutes les entêtes d'un document MDX. Par défaut, seuls les entêtes h2 et h3 sont affichés dans la table des matières. Vous pouvez changer la visibilité des niveaux de titre en définissant minHeadingLevel ou maxHeadingLevel pour les composants individuels TOCInline.

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

The toc global is just a list of heading items:

declare const toc: {
value: string;
id: string;
level: number;
}[];

Notez que le toc global est un tableau plat, donc vous pouvez facilement couper les nœuds non désirés ou insérer des nœuds supplémentaires, et créer une nouvelle arborescence de la table des matières.

import TOCInline from '@theme/TOCInline';

<TOCInline
// Only show h2 and h4 headings
toc={toc.filter((node) => node.level === 2 || node.level === 4)}
minHeadingLevel={2}
// Affiche les entêtes h4 en plus des entêtes par défaut h2 et h3
maxHeadingLevel={4}
/>

Personnalisation de la génération de la table des matières

The table-of-contents is generated by parsing the Markdown source with a Remark plugin. There are known edge-cases where it generates false-positives and false-negatives.

Markdown headings within hideable areas will still show up in the TOC. For example, headings within Tabs and details will not be excluded.

Non-Markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue.

<details>
<summary>Du détail contenant des entêtes</summary>
<h2 id="#heading-id">Je suis un entête qui n'apparaîtra pas dans la table des matières</h2>

Du contenu ...

</details>

The ability to ergonomically insert extra headings or ignore certain headings is a work-in-progress. If this feature is important to you, please report your use-case in this issue.


attention

Vous trouverez ci-dessous un contenu factice permettant de disposer de plus d'éléments dans la table des matières de la page en cours.

Exemple Section 1

Lorem ipsum

Exemple de sous-section 1 a

Lorem ipsum

Exemple de sous-sous-section 1 a I

Exemple de sous-sous-section 1 a II

Exemple de sous-sous-section 1 a III

Exemple de sous-section 1 b

Lorem ipsum

Exemple de sous-sous-section 1 b I

Exemple de sous-sous-section 1 b II

Exemple de sous-sous-section 1 b III

Exemple de sous-section 1 c

Lorem ipsum

Exemple de sous-sous-section 1 c I

Exemple de sous-sous-section 1 c II

Exemple de sous-sous-section 1 c III

Exemple Section 2

Lorem ipsum

Exemple de sous-section 2 a

Lorem ipsum

Exemple de sous-sous-section 2 a I

Exemple de sous-sous-section 2 a II

Exemple de sous-sous-section 2 a III

Exemple de sous-section 2 b

Lorem ipsum

Exemple de sous-sous-section 2 b I

Exemple de sous-sous-section 2 b II

Exemple de sous-sous-section 2 b III

Exemple de sous-section 2 c

Lorem ipsum

Exemple de sous-sous-section 2 c I

Exemple de sous-sous-section 2 c II

Exemple de sous-sous-section 2 c III

Exemple de section 3

Lorem ipsum

Exemple de sous-section 3 a

Lorem ipsum

Exemple de sous-sous-section 3 a I

Exemple de sous-sous-section 3 a II

Exemple de sous-sous-section 3 a III

Exemple de sous-section 3 b

Lorem ipsum

Exemple de sous-sous-section 3 b I

Exemple de sous-sous-section 3 b II

Exemple de sous-sous-section 3 b III

Exemple de sous-section 3 c

Lorem ipsum

Exemple de sous-sous-section 3 c I

Exemple de sous-sous-section 3 c II

Exemple de sous-sous-section 3 c III