Prise en charge Markdown

Table des matières

Standard Markdown
Extensions Markdown
Spécificités de Doxygen
Problèmes de débogage

La prise en charge de Markdown a été introduite dans la version 1.8.0 de Doxygen. Il s'agit d'une syntaxe de formatage de texte brut écrite par John Gruber, avec l'objectif de conception sous-jacent suivant :

L'objectif de la syntaxe de formatage de Markdown est de la rendre aussi lisible que possible. L'idée est qu'un document formaté en Markdown doit pouvoir être publié tel quel, en texte brut, sans donner l'impression d'avoir été marqué par des balises ou des instructions de formatage. Bien que la syntaxe de Markdown ait été influencée par plusieurs filtres texte vers HTML existants, la plus grande source d'inspiration pour la syntaxe de Markdown est le format des courriels en texte brut.

Dans la section suivante, les fonctionnalités standard de Markdown sont brièvement décrites. Le lecteur est renvoyé au site Markdown pour plus de détails.

Certaines améliorations ont été apportées, par exemple PHP Markdown Extra et GitHub flavored Markdown. La section Extensions Markdown décrit les extensions prises en charge par Doxygen.

Enfin, la section Spécificités de Doxygen décrit certaines spécificités de l'implémentation de la norme Markdown par Doxygen.

Markdown standard

Paragraphes

Même avant que Doxygen ne prenne en charge Markdown, il prenait en charge la même manière de gérer les paragraphes que Markdown : pour créer un paragraphe, il suffit de séparer les lignes consécutives de texte par une ou plusieurs lignes vides.

Un exemple :

Voici le texte d'un paragraphe.

Nous continuons avec plus de texte dans un autre paragraphe.

En-têtes

Tout comme Markdown, Doxygen prend en charge deux types d'en-têtes.

Les en-têtes de niveau 1 ou 2 peuvent être créés comme suit :

Ceci est un en-tête de niveau 1
========================

Ceci est un en-tête de niveau 2
------------------------

Un en-tête est suivi d'une ligne contenant uniquement des = ou des -. Notez que le nombre exact de = ou de - n'est pas important tant qu'il y en a au moins deux.

Vous pouvez également utiliser des # au début d'une ligne pour créer un en-tête. Le nombre de # au début de la ligne détermine le niveau (jusqu'à 6 niveaux sont pris en charge). Vous pouvez terminer un en-tête par n'importe quel nombre de #.

Voici un exemple :

# Ceci est un en-tête de niveau 1

### Ceci est un en-tête de niveau 3 #######

Citations en bloc

Les citations en bloc peuvent être créées en commençant chaque ligne par un ou plusieurs >, de manière similaire à ce qui est utilisé dans les e-mails contenant uniquement du texte.

> Ceci est une citation en bloc
> s'étendant sur plusieurs lignes

Les listes et les blocs de code (voir ci-dessous) peuvent apparaître à l'intérieur d'un bloc de citation. Les blocs de citation peuvent également être imbriqués.

Notez que Doxygen exige que vous mettiez un espace après le (dernier) caractère > pour éviter les faux positifs, c'est-à-dire lors de l'écriture

0 si OK\n
>1 si NOK

la deuxième ligne ne sera pas considérée comme une citation en bloc.

Listes

Des listes à puces simples peuvent être créées en commençant une ligne par -, + ou *.

- Élément 1

Plus de texte pour cet élément.

- Élément 2
    + élément de liste imbriqué.
    + un autre élément imbriqué.
- Élément 3

Les éléments de liste peuvent s'étendre sur plusieurs paragraphes (si chaque paragraphe commence par le retrait approprié) et les listes peuvent être imbriquées. Vous pouvez également créer une liste numérotée comme suit

1. Premier élément.
2. Deuxième élément.

Assurez-vous de lire également les extensions de listes pour les spécificités de Doxygen.

Blocs de code

Des blocs verbatim préformatés peuvent être créés en indentant chaque ligne d'un bloc de texte d'au moins 4 espaces supplémentaires

Ceci est un paragraphe normal

    Ceci est un bloc de code

Nous continuons avec un paragraphe normal à nouveau.

Doxygen supprimera l'indentation obligatoire du bloc de code. Notez que vous ne pouvez pas démarrer un bloc de code au milieu d'un paragraphe (c'est-à-dire que la ligne précédant le bloc de code doit être vide).

Voir la section Indentation du bloc de code pour plus d'informations sur la façon dont Doxygen gère l'indentation, car cela est légèrement différent du Markdown standard.

Règles horizontales

Une règle horizontale sera produite pour les lignes contenant au moins trois tirets, astérisques ou traits de soulignement ou plus. La ligne peut également inclure n'importe quelle quantité d'espaces.

Exemples :

- - -
______

Notez que l'utilisation d'astérisques dans les blocs de commentaires ne fonctionne pas. Voir Utilisation des astérisques pour plus de détails. Notez que lorsque vous utilisez des tirets et que la ligne précédente n'est pas vide, vous devez utiliser au moins un espace dans la séquence de tirets, sinon il peut être considéré comme un en-tête de niveau 2 (voir En-têtes).

Emphase

Pour mettre en valeur un fragment de texte, vous commencez et terminez le fragment par un trait de soulignement ou une étoile. L'utilisation de deux étoiles ou de traits de soulignement produira une forte emphase.

Exemples :

*astérisques simples*

_traits de soulignement simples_

**astérisques doubles**

__traits de soulignement doubles__

Voir la section Limites d'emphase et de barré pour plus d'informations sur la façon dont Doxygen gère les étendues d'emphase/barré légèrement différentes de celles du Markdown standard/GitHub Flavored Markdown.

Barré

Pour barrer un fragment de texte, vous commencez et terminez le fragment par deux tildes.

Exemples :

~~double tilde~~

Voir la section Limites d'emphase et de barré pour plus d'informations sur la façon dont Doxygen gère les étendues d'emphase/barré légèrement différemment du Markdown standard/du Markdown aromatisé à GitHub.

Code étendu

Pour indiquer une étendue de code, vous devez l'entourer de guillemets inversés `. Contrairement aux blocs de code, les étendues de code apparaissent en ligne dans un paragraphe. Un exemple :

Utilisez la fonction `printf()`.

Pour afficher un guillemet inversé littéral ou un guillemet simple à l'intérieur d'une étendue de code, utilisez des guillemets inversés doubles, c'est-à-dire :

Pour affecter la sortie de la commande `ls` à `var`, utilisez ``var=`ls```.

Pour affecter le texte 'text' à `var`, utilisez ``var='text'``.

Voir la section Limites des étendues de code pour plus d'informations sur la façon dont Doxygen gère les étendues de code légèrement différemment du Markdown standard.

Liens

Doxygen prend en charge les deux styles de liens définis par Markdown : en ligne et de référence.

Pour les deux styles, la définition du lien commence par le texte du lien délimité par [crochets].

Liens en ligne

Pour un lien en ligne, le texte du lien est suivi d'une URL et d'un titre de lien facultatif qui sont tous deux enfermés dans un ensemble de parenthèses régulières. Le titre du lien lui-même est entouré de guillemets.

Exemples :

[Le texte du lien](http://example.net/)
[Le texte du lien](http://example.net/ "Titre du lien")
[Le texte du lien](/relative/path/to/index.html "Titre du lien")
[Le texte du lien](somefile.html)

De plus, Doxygen fournit une manière similaire de lier une entité documentée :

[Le texte du lien](@ref MyClass)

Si le premier caractère non blanc de la référence est un #, cela est interprété comme un lien Doxygen et remplacé par une commande @ref :

[Le texte du lien](#MyClass)

sera interprété comme :

@ref MyClass "Le texte du lien"

Liens de référence

Au lieu de mettre l'URL en ligne, vous pouvez également définir le lien séparément et y faire référence à partir du texte.

La définition du lien se présente comme suit :

[nom du lien] : http://www.example.com « Titre facultatif »

Au lieu de guillemets doubles, des guillemets simples ou des parenthèses peuvent également être utilisés pour la partie titre.

Une fois défini, le lien se présente comme suit :

[texte du lien][nom du lien]

Si le texte et le nom du lien sont identiques, vous pouvez également utiliser

[nom du lien][]

ou même

[nom du lien]

pour faire référence au lien. Notez que la correspondance du nom du lien n'est pas sensible à la casse, comme le montre l'exemple suivant :

Je reçois 10 fois plus de trafic de [Google] que de
[Yahoo] ou [MSN].

[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"

Les définitions de liens ne seront pas visibles dans la sortie.

Comme pour les liens en ligne, Doxygen prend également en charge @ref dans une définition de lien :

[myclass]: @ref MyClass "My class"

Images

La syntaxe Markdown pour les images est similaire à celle des liens. La seule différence est un ! supplémentaire avant le texte du lien.

Exemples :

![Texte de la légende](/path/to/img.jpg)
![Texte de la légende](/path/to/img.jpg "Titre de l'image")
![Texte de la légende][img def]
![img def]

[img def]: /path/to/img.jpg "Titre facultatif"

Vous pouvez également utiliser @ref pour créer un lien vers une image :

![Texte de la légende](@ref image.png)
![img def]

[img def]: @ref image.png "Texte de la légende"

Le texte de la légende est facultatif.

Remarque
N'oubliez pas d'ajouter le chemin de l'image à IMAGE_PATH.

Lien automatique

Pour créer un lien vers une URL ou une adresse e-mail, Markdown prend en charge la syntaxe suivante :

<http://www.example.com>
<https://www.example.com>
<ftp://www.example.com>
<mailto:address@example.com>
<address@example.com>

Notez que Doxygen produira également les liens sans les chevrons.

Extensions Markdown

Table des matières

Doxygen prend en charge un marqueur de lien spécial [TOC] qui peut être placé dans une page pour produire une table des matières au début de la page, répertoriant toutes les sections.

Notez que l'utilisation de [TOC] est identique à l'utilisation d'une commande \tableofcontents.

Notez que TOC_INCLUDE_HEADINGS doit être défini sur une valeur > 0, sinon aucune table des matières n'est affichée lors de l'utilisation des en-têtes Markdown.

Tableaux

Parmi les fonctionnalités définies par « Markdown Extra », on trouve la prise en charge des tableaux simples :

Un tableau se compose d'une ligne d'en-tête, d'une ligne de séparation et d'au moins une ligne de ligne. Les colonnes du tableau sont séparées par le caractère pipe (|).

Voici un exemple :

Premier en-tête    | Deuxième en-tête
------------- ---- | ------------------
Cellule de contenu | Cellule de contenu
Cellule de contenu | Cellule de contenu

ce qui produira le tableau suivant :

Premier en-tête	Deuxième en-tête
Cellule de contenu	Cellule de contenu
Cellule de contenu	Cellule de contenu

L'alignement des colonnes peut être contrôlé via un ou deux deux-points sur la ligne de séparation d'en-tête :

| Droite | Centre | Gauche |
| ----:  | :----: | :----   |
| 10     | 10     | 10     |
| 1000   | 1000   | 1000   |

qui se présente comme suit :

Droite	Centre	Gauche
10	10	10
1000	1000	1000

De plus, les étendues de colonnes et de lignes sont prises en charge. L'utilisation d'un accent circonflexe (« ^ ») dans une cellule indique que la cellule située au-dessus doit s'étendre sur plusieurs lignes. Des séquences d'accent circonflexe peuvent être utilisées pour n'importe quel nombre d'étendues de lignes. Par exemple :

| Droite | Centre | Gauche |
| ----:  | :----: | :----  |
| 10     | 10     | 10     |
| ^      | 1000   | 1000   |

qui se présente comme suit :

Droite	Centre	Gauche
10	10	10
^	1000	1000

Les portées de colonnes sont prises en charge au moyen de barres verticales directement adjacentes («| »). Chaque barre verticale supplémentaire indique une colonne supplémentaire à couvrir. En d'autres termes, une seule barre verticale indique une portée de colonne unique, deux barres verticales indiquent une portée de 2 colonnes, et ainsi de suite. Par exemple :

| Droite | Centre | Gauche |
| ----:  | :----: | :----  |  
| 10     | 10     | 10     |
| 1000   |||

qui ressemblera à ceci :

Droite	Centre	Gauche
10	10	10
1000

Pour des tableaux plus complexes dans Doxygen, veuillez consulter : Tableaux inclus.

Blocs de code délimités

Une autre fonctionnalité définie par « Markdown Extra » est la prise en charge des blocs de code délimités :

Un bloc de code délimité ne nécessite pas d'indentation et est défini par une paire de « lignes de délimitation ». Une telle ligne se compose de 3 caractères tilde (~) ou plus sur une ligne. La fin du bloc doit avoir le même nombre de tildes. Voici un exemple :

Ceci est un paragraphe présentant :

~~~~~~~~~~~~~~~~~~~~~
un bloc de code d'une seule ligne
~~~~~~~~~~~~~~~~~~~~~~

Par défaut, la sortie est la même que pour un bloc de code normal.

Pour les langages pris en charge par Doxygen, vous pouvez également faire apparaître le bloc de code avec la coloration syntaxique. Pour ce faire, vous devez indiquer l'extension de fichier typique qui correspond au langage de programmation après le dernier signe de délimitation. Pour une mise en évidence selon le langage Python par exemple, vous devez écrire ce qui suit :

~~~~~~~~~~~~~{.py}
# Une classe
class Dummy:
pass
~~~~~~~~~~~~~

ce qui produira :

# Une classe
class Dummy:
    pass

et pour C vous écririez :

~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~

ce qui produira :

int func(int a,int b) { return a*b; }

Le point est facultatif, les accolades sont facultatives lorsque le nom de ce langage commence par un caractère alphabétique et que les autres caractères sont des caractères alphanumériques ou un signe plus.

Une autre façon de désigner les blocs de code délimités consiste à utiliser 3 ou plusieurs guillemets (```) :

```
également un bloc de code délimité
```

Pour les formats d'image dot, msc et plantuml, le bloc délimité sera affiché sous forme d'image à condition que le format d'image soit activé (voir HAVE_DOT et PLANTUML_JAR_PATH) sinon il est affiché sous forme de code brut.

Exemple :

```plantuml
Alice -> Bob
```

ou

```plantuml
@startuml
Alice -> Bob
@enduml
```

Attributs d'ID d'en-tête

Le Markdown standard ne prend pas en charge l'étiquetage des en-têtes, ce qui est un problème si vous souhaitez créer un lien vers une section.

PHP Markdown Extra vous permet d'étiqueter un en-tête en ajoutant ce qui suit à l'en-tête :

En-tête 1 {#labelid}
========

## En-tête 2 ## {#labelid2}

Pour créer un lien vers une section dans le même bloc de commentaires, vous pouvez utiliser

[Texte du lien](#labelid)

pour créer un lien vers une section en général, Doxygen vous permet d'utiliser @ref.

[Texte du lien](@ref labelid)

Notez que cela ne fonctionne que pour les en-têtes de niveau 1 à 4.

Attributs d'image

Le Markdown standard ne prend pas en charge le contrôle des dimensions des images, ce qui réduit la flexibilité lors de la rédaction de documents.

PHP Markdown Extra vous permet d'ajouter des attributs supplémentaires à une image comme dans :

![Texte de la légende](/path/to/img.jpg){attributes}

Pour autoriser les attributs spécifiques au format de sortie, la syntaxe suivante est prise en charge :

![Texte de la légende](/path/to/img.jpg){format : attributs, format : attributs}

Pour une description des possibilités, consultez le paragraphe Indication de la taille pour la commande \image.

Par exemple :

![Logo Doxygen](https://www.doxygen.org/images/doxygen.png){html : width=50%, latex : width=5cm}

Spécificités de Doxygen

Même si Doxygen essaie de suivre la norme Markdown aussi étroitement que possible, il existe quelques écarts et ajouts de spécificités Doxygen.

Inclure les fichiers Markdown sous forme de pages

Doxygen peut traiter les fichiers au format Markdown. Pour que cela fonctionne, l'extension d'un tel fichier doit être .md ou .markdown (consultez EXTENSION_MAPPING si vos fichiers Markdown ont une extension différente et utilisez md comme nom de l'analyseur). Chaque fichier est converti en page (consultez la commande page pour plus de détails). Doxygen ne créera pas de page dédiée si le fichier Markdown commence par une commande dédiée (ex : \defgroup, \dir) pour éviter de créer une page vide lorsque le fichier ne contient que de la documentation sur les répertoires ou les groupes. Un fichier README.md dans un sous-répertoire sera traité comme une documentation de répertoire, à moins qu'il ne soit explicitement remplacé par une commande dédiée (ex : @page, @mainpage) pour créer une nouvelle page.

Par défaut, le nom et le titre de la page sont dérivés du nom du fichier. Cependant, si le fichier commence par un en-tête de niveau 1, il est utilisé comme titre de la page. Si vous spécifiez un libellé pour l'en-tête (comme indiqué dans les attributs d'ID d'en-tête), Doxygen l'utilisera comme nom de page.

Si le libellé s'appelle index ou mainpage, Doxygen placera la documentation sur la page d'accueil (index.html).

Voici un exemple de fichier README.md qui apparaîtra comme page principale lorsqu'il sera traité par Doxygen :

Ma page principale  {#mainpage}
============

Documentation qui apparaîtra sur la page principale

Si une page a un libellé, vous pouvez créer un lien vers celui-ci en utilisant @ref comme indiqué ci-dessus. Pour faire référence à une page Markdown sans une telle étiquette, vous pouvez simplement utiliser le nom de fichier de la page, par exemple

Voir [l'autre page](other.md) pour plus d'informations.

Traitement des blocs HTML

Markdown est assez strict dans la façon dont il traite le HTML au niveau du bloc :

Les éléments HTML au niveau du bloc (par exemple, div, table, pre, p, etc.) doivent être séparés du contenu environnant par des lignes vides, et les balises de début et de fin du bloc ne doivent pas être indentées avec des tabulations ou des espaces.

Doxygen n'a pas cette exigence et traitera également le formatage Markdown à l'intérieur de ces blocs HTML. La seule exception concerne les blocs <pre>, qui sont transmis intacts (pratique pour l'art ASCII).

Doxygen ne traitera pas le formatage Markdown à l'intérieur des blocs verbatim ou de code, et dans d'autres sections qui doivent être traitées sans modifications (par exemple les formules ou les graphiques à points en ligne).

Indentation du bloc de code

Markdown permet à la fois une seule tabulation ou 4 espaces pour démarrer un bloc de code. Étant donné que Doxygen remplace déjà les tabulations par des espaces avant d'effectuer le traitement Markdown, l'effet ne sera le même que si TAB_SIZE dans le fichier de configuration a été défini sur 4. Lorsqu'il est défini sur une valeur plus élevée, des espaces seront présents dans le bloc de code. Une valeur inférieure empêchera qu'une seule tabulation soit interprétée comme le début d'un bloc de code.

Avec Markdown, tout bloc indenté de 4 espaces (et de 8 espaces à l'intérieur des listes) est traité comme un bloc de code. Ce montant d'indentation est absolu, c'est-à-dire qu'il compte à partir du début de la ligne.

Étant donné que les commentaires Doxygen peuvent apparaître à n'importe quel niveau d'indentation requis par le langage de programmation, il utilise à la place une indentation relative. Le montant d'indentation est compté par rapport au paragraphe précédent. S'il n'y a pas de paragraphe précédent (c'est-à-dire que vous souhaitez commencer par un bloc de code), le montant minimal d'indentation de l'ensemble du bloc de commentaires est utilisé comme référence.

Dans la plupart des cas, cette différence n'entraîne pas de sortie différente. La différence n'est perceptible que si vous jouez avec l'indentation des paragraphes :

texte

 texte

  texte

   code

Dans ce cas, Markdown placera le mot code dans un bloc de code, tandis que Doxygen le traitera comme du texte normal, car bien que l'indentation absolue soit de 4, l'indentation par rapport au paragraphe précédent n'est que de 1.

Notez que les marqueurs de liste ne sont pas pris en compte lors de la détermination de l'indentation relative :

1. Élément 1

    Plus de texte pour l'élément 1

2. Élément 2

        Bloc de code pour l'élément 2

Pour l'élément 1, l'indentation est de 4 (lorsque le marqueur de liste est traité comme un espace blanc), donc le paragraphe suivant « Plus de texte … » commence au même niveau d'indentation et n'est donc pas considéré comme un bloc de code.

Limites d'emphase et de barré

Contrairement à Markdown standard et Markdown aromatisé à GitHub, Doxygen ne touchera pas aux traits de soulignement internes, aux étoiles ou aux tildes, donc ce qui suit apparaîtra tel quel :

a_nice_identifier

De plus, un * ou un _ ne commence une emphase et un ~ ne commence un barré que si :

il est suivi d'un caractère alphanumérique, et
il est précédé d'un espace, d'un saut de ligne ou de l'un des caractères suivants <{([,:;.

Une emphase ou un barré se termine si :

il n'est pas suivi d'un caractère alphanumérique, et
il n'est pas précédé d'un espace, d'un saut de ligne ou de l'un des caractères suivants ({[<=+-\@.

La durée de l'emphase ou du barré est limitée à un seul paragraphe.

Enfin, notez que lorsque vous souhaitez mettre l'accent sur un morceau de texte au début d'une ligne au moyen de * dans un bloc de commentaires Doxygen de style C (c'est-à-dire /** ... */) qui n'a pas de * en tête comme colonne "lineup", alors Doxygen verra la séquence de * au début de la ligne comme "lineup" et non comme une emphase. Ainsi, ce qui suit ne sera pas rendu en gras :

/**
**ce n'est pas en gras**
*/

cependant, ce sera rendu en gras :

/**
* **ceci est en gras**
*/

Limites de code étendu

Notez que contrairement au Markdown standard, Doxygen laisse ce qui suit intact.

Un mot « cool » dans une phrase « sympa ».

En d'autres termes ; un guillemet simple annule le traitement spécial d'une étendue de code enveloppée dans une paire de caractères de backtick. Cette restriction supplémentaire a été ajoutée pour des raisons de compatibilité ascendante.

Si vous souhaitez avoir des guillemets simples à l'intérieur d'une étendue de code, n'utilisez pas un seul backtick mais deux backticks autour de l'étendue de code.

Extensions de listes

Avec Markdown, deux listes séparées par une ligne vide sont jointes en une seule liste, ce qui peut être plutôt inattendu et beaucoup de gens considèrent cela comme un bug. Cependant, Doxygen créera deux listes distinctes, comme vous vous en doutez.

Exemple :

- Élément 1 de la liste 1
- Élément 2 de la liste 1

1. Élément 1 de la liste 2
2. Élément 2 de la liste 2

Avec Markdown, les numéros réels que vous utilisez pour marquer la liste n'ont aucun effet sur la sortie HTML produite par Markdown. Par exemple, le Markdown standard traite les éléments suivants comme une liste avec 3 éléments numérotés :

1. Élément 1
1. Élément 2
1. Élément 3

Doxygen exige cependant que les numéros utilisés comme marques soient strictement dans l'ordre croissant, donc l'exemple ci-dessus produirait 3 listes avec un élément. Un élément avec un numéro égal ou inférieur à l'élément précédent démarrera une nouvelle liste. Par exemple :

1. Élément 1 de la liste 1
3. Élément 2 de la liste 1
2. Élément 1 de la liste 2
4. Élément 2 de la liste 2

produira :

1. Élément 1 de la liste 1
2. Élément 2 de la liste 1

1. Élément 1 de la liste 2
2. Élément 2 de la liste 2

Historiquement, Doxygen dispose d'un moyen supplémentaire de créer des listes numérotées en utilisant les marqueurs -# :

-# élément 1
-# élément 2

Les listes avec comme indicateur une case à cocher cochée ou non cochée utilisent les marqueurs - [ ] ou - [x] ou - [X] :

- [ ] non coché
- [x] coché

Utilisation des astérisques

Une attention particulière doit être portée lors de l'utilisation de * dans un bloc de commentaires pour démarrer une liste ou créer une règle.

Doxygen supprimera tous les * de début du commentaire avant de procéder au traitement Markdown. Ainsi, bien que ce qui suit fonctionne bien

    /** Une liste :
    *  * item1
    *  * item2
    */

Lorsque vous supprimez les * de début, Doxygen supprime également les autres étoiles, ce qui fait disparaître la liste !

Les règles créées avec des * ne seront pas du tout visibles. Elles ne fonctionnent que dans les fichiers Markdown.

Limites de la portée du balisage

Pour éviter qu'un * ou un _ errant ne corresponde à quelque chose plusieurs paragraphes plus loin et montre tout ce qui se trouve entre les deux avec emphase, Doxygen limite la portée d'un * et d'un _ à un seul paragraphe.

Pour une étendue de code, entre le backtick de début et de fin, seules deux nouvelles lignes sont autorisées.

Il existe également des limites pour les liens : le texte du lien et le titre du lien ne peuvent contenir qu'une seule nouvelle ligne, l'URL ne peut contenir aucune nouvelle ligne.

Prise en charge des alertes GitHub

Dans la version GitHub de Markdown, il existe une prise en charge des alertes, dont la syntaxe est similaire à une citation en bloc d'un niveau suivie de [!<alert>] où <alert> peut être une note, un warning, un caution ou un important. Dans Doxygen, ces alertes sont traduites en commandes Doxygen normales :

>[!note] est traduit par \note
> [!warning] est traduit par \warning
> [!tip] est traduit par \remark
> [!caution] est traduit par \attention
> [!important] est traduit par \important

Exemple :

> [!note]
> The special text for the note

qui sera rendu comme :

note

Problèmes de débogage

Lorsque Doxygen analyse le code source, il extrait d'abord les blocs de commentaires, puis les transmet au préprocesseur Markdown. La sortie du prétraitement Markdown se compose de texte avec des commandes spéciales et des commandes HTML. Un deuxième passage prend la sortie du préprocesseur Markdown et la convertit dans les différents formats de sortie.

Pendant le prétraitement Markdown, aucune erreur n'est générée. Tout ce qui ne correspond pas à la syntaxe Markdown est simplement transmis tel quel. Dans la phase d'analyse suivante, cela peut entraîner des erreurs, qui ne sont pas toujours évidentes car elles sont basées sur le format intermédiaire.

Pour voir le résultat après le traitement Markdown, vous pouvez exécuter Doxygen avec l'option Markdown -d. Il imprimera ensuite chaque bloc de commentaires avant et après le traitement Markdown.