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}
Use the write-heading-ids
CLI command to add explicit IDs to all your Markdown documents.
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.
---
# 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.
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.
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} />
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}
/>
- Markdown headings
- Table of contents heading level
- Inline table of contents
- Customizing table of contents generation
- Example Section 1
- 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-sous-section 1 b I
- Exemple de sous-sous-section 1 b II
- Exemple de sous-sous-section 1 b III
- 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
- 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-sous-section 2 b I
- Exemple de sous-sous-section 2 b II
- Exemple de sous-sous-section 2 b III
- 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
- 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-sous-section 3 b I
- Exemple de sous-sous-section 3 b II
- Exemple de sous-sous-section 3 b III
- Exemple de sous-sous-section 3 c I
- Exemple de sous-sous-section 3 c II
- Exemple de sous-sous-section 3 c III
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.
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