Créer une table des matières automatique en Markdown

11 décembre 2025 • 10 min de lecture

Une table des matières automatique est essentielle pour structurer et naviguer dans les documents longs. En Markdown, plusieurs techniques permettent de générer un sommaire dynamique qui se met à jour automatiquement lorsque vous modifiez vos titres. Ce guide complet vous présente toutes les méthodes pour créer une table des matières professionnelle dans vos documents Markdown et PDF.

Pourquoi une table des matières automatique ?

Les avantages d'une table des matières générée automatiquement sont multiples :

Gain de temps : Plus besoin de la maintenir manuellement lors de chaque modification
Cohérence garantie : Le sommaire reflète toujours la structure réelle du document
Navigation facilitée : Liens cliquables vers chaque section (dans les PDF et HTML)
Professionnalisme : Donne une apparence structurée et soignée à vos documents
Accessibilité : Aide les lecteurs à comprendre rapidement l'organisation du contenu

Structure hiérarchique des titres

Avant de créer une table des matières, assurez-vous que votre document utilise correctement la hiérarchie des titres Markdown :

# Titre principal (H1) - Une seule fois dans le document

## Section principale (H2)
Contenu de la section...

### Sous-section (H3)
Détails...

#### Sous-sous-section (H4)
Plus de détails...

## Autre section principale (H2)
...

Bonnes pratiques :

Utilisez un seul H1 pour le titre du document
Ne sautez pas de niveaux (pas de H4 directement après un H2)
Gardez des titres courts et descriptifs
Évitez les caractères spéciaux dans les titres (pour la génération des ancres)

Méthodes de génération

Méthode 1 : Marqueur automatique (extensions Markdown)

Certains processeurs Markdown, dont MD2PDF, supportent un marqueur spécial qui génère automatiquement la table des matières :

# Mon document

[TOC]

## Introduction
Contenu de l'introduction...

## Méthode
Description de la méthode...

Alternatives au marqueur [TOC] selon les systèmes :

[TOC] : GitLab, Typora
[[_TOC_]] : GitHub (dans les wikis)
{:toc} : Jekyll
@[toc] : VuePress

Méthode 2 : Table des matières manuelle avec liens

Vous pouvez créer une table des matières manuelle en utilisant les ancres automatiques générées par Markdown :

# Guide complet

## Table des matières

- [Introduction](#introduction)
- [Installation](#installation)
  - [Prérequis](#prérequis)
  - [Configuration](#configuration)
- [Utilisation](#utilisation)
- [Conclusion](#conclusion)

## Introduction
Texte de l'introduction...

## Installation
Instructions d'installation...

Règles de génération des ancres :

Tout en minuscules
Espaces remplacés par des tirets -
Caractères spéciaux supprimés
Accents conservés (selon le parser)

Exemples :

## Installation du logiciel → #installation-du-logiciel
## Étapes d'utilisation → #étapes-dutilisation
## FAQ (Questions fréquentes) → #faq-questions-fréquentes

Générez automatiquement vos tables des matières en PDF

Essayer MD2PDF →

Méthode 3 : Outils en ligne de commande

Plusieurs outils CLI génèrent automatiquement une table des matières dans vos fichiers Markdown :

markdown-toc (Node.js)

npm install -g markdown-toc

# Génération
markdown-toc document.md

# Insertion automatique dans le fichier
markdown-toc -i document.md

doctoc (Node.js)

npm install -g doctoc

# Génération pour un fichier
doctoc document.md

# Génération pour tous les fichiers Markdown
doctoc docs/

gh-md-toc (Bash)

wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc
chmod a+x gh-md-toc

./gh-md-toc document.md

Méthode 4 : Extensions d'éditeurs

Visual Studio Code

Extensions recommandées :

Markdown All in One : Génère et met à jour la TOC avec Ctrl+Shift+P → "Create Table of Contents"
Markdown TOC : Génération automatique à la sauvegarde

Obsidian

Plugin natif "Outline" ou utilisez :

```toc
```

Typora

Menu → Paragraph → Table of Contents ou tapez [toc]

Personnalisation de la table des matières

Contrôler les niveaux de profondeur

Pour limiter la table des matières aux titres de niveau 2 et 3 uniquement :

Avec markdown-toc

markdown-toc --maxdepth 3 document.md

Avec MD2PDF

MD2PDF permet de configurer la profondeur de la table des matières via les options de conversion :

toc:
  enabled: true
  depth: 3
  title: "Sommaire"

Exclure certains titres

Pour exclure un titre de la table des matières, ajoutez un commentaire HTML :

## Titre normal (inclus dans la TOC)


## Titre exclu (ne sera pas dans la TOC)

## Autre titre normal

Personnaliser le style

La présentation de la table des matières peut être personnalisée avec CSS lors de la conversion en PDF :

<style>
.toc {
  background-color: #f5f5f5;
  padding: 20px;
  border-left: 4px solid #db2c46;
}

.toc ul {
  list-style-type: none;
}

.toc a {
  color: #333;
  text-decoration: none;
}
</style>

Table des matières avec numérotation

Pour ajouter une numérotation automatique des sections :

Numérotation manuelle

## Table des matières

1. [Introduction](#1-introduction)
2. [Méthode](#2-méthode)
   1. [Étape 1](#21-étape-1)
   2. [Étape 2](#22-étape-2)
3. [Conclusion](#3-conclusion)

## 1. Introduction
...

## 2. Méthode
...

### 2.1 Étape 1
...

Numérotation automatique avec CSS (dans le PDF)

MD2PDF peut appliquer une numérotation CSS automatique :

<style>
body { counter-reset: h2 }
h2 { counter-reset: h3 }
h3 { counter-reset: h4 }

h2:before {
  counter-increment: h2;
  content: counter(h2) ". "
}

h3:before {
  counter-increment: h3;
  content: counter(h2) "." counter(h3) ". "
}
</style>

Table des matières multi-niveaux

Exemple complet d'une table des matières à quatre niveaux :

# Documentation complète

## Sommaire

- [1. Introduction](#1-introduction)
- [2. Installation](#2-installation)
  - [2.1 Prérequis système](#21-prérequis-système)
    - [2.1.1 Matériel](#211-matériel)
    - [2.1.2 Logiciels](#212-logiciels)
  - [2.2 Procédure d'installation](#22-procédure-dinstallation)
- [3. Configuration](#3-configuration)
  - [3.1 Configuration de base](#31-configuration-de-base)
  - [3.2 Options avancées](#32-options-avancées)
- [4. Utilisation](#4-utilisation)
- [5. Dépannage](#5-dépannage)
- [6. Annexes](#6-annexes)

Intégration avec MD2PDF

MD2PDF offre plusieurs fonctionnalités avancées pour les tables des matières :

Génération automatique activée

Par défaut, MD2PDF génère une table des matières cliquable dans le PDF. Les signets (bookmarks) du PDF correspondent automatiquement à la structure des titres de votre document Markdown.

Options de configuration

---
toc:
  enabled: true
  depth: 3
  position: top
  title: "Table des matières"
  numbered: true
---

# Mon document
...

Style personnalisé

Utilisez les templates MD2PDF pour personnaliser complètement l'apparence de votre table des matières :

Couleurs et polices personnalisées
Indentation et espacement
Numérotation de page automatique
Liens hypertextes cliquables

Cas d'usage professionnels

Documentation technique

Pour les guides et manuels longs, une table des matières détaillée est indispensable :

# Manuel d'utilisation v2.0

## Sommaire

- [Guide de démarrage rapide](#guide-de-démarrage-rapide)
- [Architecture système](#architecture-système)
- [API Reference](#api-reference)
  - [Authentification](#authentification)
  - [Endpoints](#endpoints)
- [Exemples de code](#exemples-de-code)
- [FAQ](#faq)

Rapports d'analyse

# Rapport d'analyse trimestriel

## Sommaire exécutif

## Table des matières

1. [Résumé](#résumé)
2. [Méthodologie](#méthodologie)
3. [Résultats](#résultats)
4. [Analyse détaillée](#analyse-détaillée)
5. [Recommandations](#recommandations)
6. [Conclusion](#conclusion)
7. [Annexes](#annexes)

Livres et ebooks

# Titre du livre

## Table des matières

### Partie I : Les fondamentaux
- Chapitre 1 : Introduction
- Chapitre 2 : Concepts de base
- Chapitre 3 : Première application

### Partie II : Techniques avancées
- Chapitre 4 : Optimisation
- Chapitre 5 : Sécurité
- Chapitre 6 : Performance

### Partie III : Cas pratiques
- Chapitre 7 : Étude de cas 1
- Chapitre 8 : Étude de cas 2

Automatisation avec scripts

Script de génération pré-commit (Git)

#!/bin/bash
# .git/hooks/pre-commit

# Génère la TOC avant chaque commit
doctoc README.md docs/*.md

git add README.md docs/*.md

Intégration CI/CD

# .github/workflows/toc.yml
name: Update TOC
on: [push]
jobs:
  update-toc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: technote-space/toc-generator@v4

Bonnes pratiques

Placez la TOC en début de document : Juste après le titre principal et l'introduction
Limitez la profondeur : 3 niveaux maximum pour éviter une TOC trop longue
Titres descriptifs : Chaque titre doit être compréhensible hors contexte
Cohérence : Gardez un style uniforme dans tous vos documents
Mise à jour : Automatisez pour éviter les erreurs humaines
Testez les liens : Vérifiez que tous les liens de la TOC fonctionnent

Dépannage

Les liens ne fonctionnent pas

Vérifiez que les ancres respectent les conventions (minuscules, tirets)
Supprimez les caractères spéciaux des titres
Testez dans différents lecteurs PDF

La TOC n'apparaît pas

Vérifiez que le marqueur est sur sa propre ligne
Assurez-vous que votre processeur Markdown le supporte
Consultez la documentation de votre outil de conversion

Numérotation incorrecte

Vérifiez la hiérarchie des titres (pas de saut de niveau)
Testez avec différents outils de génération
Utilisez la validation de structure Markdown

Conclusion

Une table des matières automatique est un élément essentiel pour structurer vos documents Markdown longs et améliorer l'expérience de lecture. Que vous utilisiez des marqueurs spéciaux, des outils CLI ou des extensions d'éditeur, l'automatisation de cette tâche vous fait gagner un temps précieux et garantit la cohérence de votre documentation.

Avec MD2PDF, la génération de table des matières est entièrement automatisée et personnalisable. Vos documents PDF incluent automatiquement un sommaire cliquable avec signets de navigation, offrant une expérience de lecture professionnelle comparable aux documents créés avec des outils de PAO traditionnels.