Aller au contenu principal
Version : 2.4.0

Entêtes et table des matières

Markdown headings​

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.

Heading IDs​

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. For example, ### Hello World will have ID hello-world.

Generated IDs have some limitations:

  • L'ID pourrait ne pas être correct
  • You might want to change or translate the text without updating the existing ID

A special Markdown syntax lets you set an explicit heading id:

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

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

Avoid colliding IDs

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.

Table of contents heading level​

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.

To set the heading level for a particular page, use the toc_min_heading_level and toc_max_heading_level front matter.

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

The themeConfig option would apply to all TOC on the site, including inline TOC, but front matter options only affect the top-right TOC. You need to use the minHeadingLevel and maxHeadingLevel props to customize each <TOCInline /> component.

Inline table of contents​

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

The toc variable is available in any MDX document and contains all the headings of an MDX document. By default, only h2 and h3 headings are displayed in the TOC. You can change which heading levels are visible by setting minHeadingLevel or maxHeadingLevel for individual TOCInline components.

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />
http://localhost:3000

The toc global is just a list of heading items:

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

Note that the toc global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.

import TOCInline from '@theme/TOCInline';

<TOCInline
  // Only show h2 and h4 headings
  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
  minHeadingLevel={2}
  // Show h4 headings in addition to the default h2 and h3 headings
  maxHeadingLevel={4}
/>
http://localhost:3000

Customizing table of contents generation​

The table-of-contents is generated by parsing the Markdown source with a Remark plugin. Il existe des cas connus où il génère des faux positifs et des faux négatifs.

Les entêtes Markdown dans des zones cachées apparaîtront toujours dans la table des matières. For example, headings within Tabs and details will not be excluded.

Les entêtes non-Markdown n'apparaîtront pas dans la table des matières. Cela peut être utilisé à votre avantage pour résoudre le problème précédemment mentionné.

<details>
<summary>Some details containing headings</summary>
<h2 id="#heading-id">I'm a heading that will not show up in the TOC</h2>

Some content...

</details>

La possibilité d'insérer de manière ergonomique des entêtes supplémentaires ou d'ignorer certaines entêtes est en cours de développement. 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.

Example Section 1​

Lorem ipsum

Example Subsection 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​

Example Subsection 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​

Example Subsection 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​

Example Section 2​

Lorem ipsum

Example Subsection 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​

Example Subsection 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​

Example Subsection 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​

Example Section 3​

Lorem ipsum

Example Subsection 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​

Example Subsection 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​

Example Subsection 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​