Markdown 支持于 Doxygen 1.8.0 版本引入。它是由 John Gruber 编写的一种纯文本格式化语法，其基本设计目标如下：
Markdown 格式语法的设计目标是使其尽可能易读。其理念是，Markdown 格式的文档应该能够按原样发布，作为纯文本，而不会看起来像是被标签或格式说明标记过。虽然 Markdown 的语法受到一些现有文本到 HTML 过滤器的影响，但 Markdown 语法最大的灵感来源是纯文本电子邮件的格式。
在下一节中，将简要讨论标准 Markdown 功能。有关更多详细信息，请参阅 Markdown 网站。
Doxygen 引入了一些增强功能，例如 PHP Markdown Extra 和 GitHub flavored Markdown。Markdown 扩展一节讨论了 Doxygen 支持的扩展。
最后，Doxygen 特性一节讨论了 Doxygen 实现 Markdown 标准的一些具体细节。
即使在 Doxygen 支持 Markdown 之前，它也支持与 Markdown 相同的段落处理方式：要创建段落，只需用一个或多个空行分隔连续的文本行。
一个例子
Here is text for one paragraph. We continue with more text in another paragraph.
与 Markdown 一样，Doxygen 支持两种类型的标题
可以如下制作一级或二级标题
This is a level 1 header ======================== This is a level 2 header ------------------------
标题后面跟着一行只包含“=”或“-”的行。请注意，“=”或“-”的准确数量不重要，只要至少有两个即可。
或者，您可以在行首使用“#”来制作标题。行首的“#”数量决定了级别（最多支持 6 个级别）。您可以使用任意数量的“#”来结束标题。
这是一个例子
# This is a level 1 header ### This is level 3 header #######
块引用可以通过以一个或多个“>”开头每一行来创建，类似于纯文本电子邮件中使用的形式。
> This is a block quote > spanning multiple lines
列表和代码块（见下文）可以出现在引用块内。引用块也可以嵌套。
请注意，Doxygen 要求您在（最后一个）“>”字符后加一个空格，以避免误报，即在写入时
0 if OK\n >1 if NOK
第二行将不被视为块引用。
简单的项目符号列表可以通过以“-”、“+”或“*”开头一行来创建。
- Item 1 More text for this item. - Item 2 + nested list item. + another nested item. - Item 3
列表项可以跨多个段落（如果每个段落都以适当的缩进开始），并且列表可以嵌套。您还可以制作一个编号列表，如下所示：
1. First item. 2. Second item.
请务必阅读列表扩展以了解 Doxygen 的具体内容。
预格式化逐字块可以通过将文本块中的每一行至少多缩进 4 个空格来创建。
This a normal paragraph
This is a code block
We continue with a normal paragraph again.
Doxygen 将从代码块中删除强制缩进。请注意，您不能在段落中间开始代码块（即代码块之前的行必须为空）。
有关 Doxygen 如何处理缩进的更多信息，请参阅代码块缩进部分，因为这与标准 Markdown 略有不同。
包含至少三个或更多连字符、星号或下划线的行将生成水平分隔线。该行还可以包含任意数量的空格。
示例
- - - ______
请注意，在注释块中使用星号不起作用。有关详细信息，请参阅星号的使用。
请注意，当使用连字符且前一行不为空时，您必须在连字符序列中使用至少一个空格，否则它可能会被视为二级标题（请参阅标题）。
要强调文本片段，您可以使用下划线或星号开始和结束该片段。使用两个星号或下划线将产生强强调。三个星号或下划线将结合前两种选项的强调。
示例
*single asterisks* _single underscores_ **double asterisks** __double underscores__ ***triple asterisks*** ___triple underscores___
有关 Doxygen 如何处理强调/删除线跨度与标准 Markdown / GitHub Flavored Markdown 略有不同的更多信息，请参阅强调和删除线限制部分。
要对文本片段应用删除线，请使用两个波浪号开始和结束该片段。
示例
~~double tilde~~
有关 Doxygen 如何处理强调/删除线跨度与标准 Markdown / GitHub Flavored Markdown 略有不同的更多信息，请参阅强调和删除线限制部分。
要表示一段代码，您应该将其用反引号（ ` ）括起来。与代码块不同，代码跨度在段落中内联显示。一个例子：
Use the `printf()` function.
要在代码跨度内显示字面反引号或单引号，请使用双反引号，即
To assign the output of command `ls` to `var` use ``var=`ls```. To assign the text 'text' to `var` use ``var='text'``.
有关 Doxygen 如何处理代码跨度与标准 Markdown 略有不同的更多信息，请参阅代码跨度限制部分。
Doxygen 支持 Markdown 定义的两种链接制作样式：内联和引用。
对于这两种样式，链接定义都以方括号 [square brackets] 括起来的链接文本开始。
对于内联链接，链接文本后面跟着一个 URL 和一个可选的链接标题，它们一起包含在一对常规括号中。链接标题本身用引号括起来。
示例
[The link text](http://example.net/) [The link text](http://example.net/ "Link title") [The link text](/relative/path/to/index.html "Link title") [The link text](somefile.html)
此外，Doxygen 提供了一种类似的方式来链接已记录的实体
[The link text](@ref MyClass)
如果引用的第一个非空白字符是 #，则这被解释为 Doxygen 链接，并替换为 @ref 命令。
[The link text](#MyClass)
将被解释为
@ref MyClass "The link text"
除了将 URL 内联放置之外，您还可以单独定义链接，然后在文本中引用它。
链接定义如下所示：
[link name]: http://www.example.com "Optional title"
除了双引号，标题部分也可以使用单引号或括号。
定义后，链接如下所示：
[link text][link name]
如果链接文本和名称相同，也可以
[link name][]
甚至
[link name]
可用于引用链接。请注意，链接名称匹配不区分大小写，如以下示例所示：
I get 10 times more traffic from [Google] than from [Yahoo] or [MSN]. [google]: http://google.com/ "Google" [yahoo]: http://search.yahoo.com/ "Yahoo Search" [msn]: http://search.msn.com/ "MSN Search"
链接定义在输出中不可见。
与内联链接一样，Doxygen 也支持在链接定义中使用 @ref。
[myclass]: @ref MyClass "My class"
Markdown 图片的语法与链接类似。唯一的区别是在链接文本前多了一个“!”。
示例
  ![Caption text][img def] ![img def] [img def]: /path/to/img.jpg "Optional Title"
您也可以在此处使用 @ref 链接图片。
 ![img def] [img def]: @ref image.png "Caption text"
标题文本是可选的。
要创建指向 URL 或电子邮件地址的链接，Markdown 支持以下语法：
<http://www.example.com> <https://www.example.com> <ftp://www.example.com> <mailto:[email protected]> <[email protected]>
请注意，Doxygen 也会生成不带尖括号的链接。
Doxygen 支持一个特殊的链接标记 [TOC]，它可以放置在页面中，以便在页面开头生成一个目录，列出所有章节。
请注意，使用 [TOC] 与使用 \tableofcontents 命令相同。
请注意，TOC_INCLUDE_HEADINGS 必须设置为大于 0 的值，否则在使用 Markdown 标题时将不显示目录。
“Markdown Extra”定义的功能之一是支持简单表格
一个表格由一个标题行、一个分隔行和至少一个行组成。表格列用竖线 (|) 字符分隔。
这是一个例子
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
将生成以下表格
| 第一个标题 | 第二个标题 |
|---|---|
| 内容单元格 | 内容单元格 |
| 内容单元格 | 内容单元格 |
列对齐可以通过标题分隔线处的一个或两个冒号来控制
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 | 1000 | 1000 |
这将如下所示
| 右对齐 | 居中 | 左对齐 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | 1000 | 1000 |
此外，还支持列和行跨度。在单元格中使用插入符号 ("^") 表示上面的单元格应该跨行。插入符号序列可用于任意数量的行跨度。例如：
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | ^ | 1000 | 1000 |
这将如下所示
| 右对齐 | 居中 | 左对齐 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | 1000 |
列跨度通过直接相邻的竖线 ("|") 支持。每个额外的竖线表示一个额外的列要跨越。换句话说，一个竖线表示一个列跨度，两个竖线表示两个列跨度，依此类推。例如：
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 |||
这将如下所示
| 右对齐 | 居中 | 左对齐 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | ||
对于 Doxygen 中更复杂的表格，请参阅：包含表格
“Markdown Extra”定义的另一个功能是支持围栏式代码块
围栏式代码块不需要缩进，由一对“围栏线”定义。这样的行由行中 3 个或更多波浪号 (~) 字符组成。块的末尾应具有相同数量的波浪号。这是一个例子：
This is a paragraph introducing: ~~~~~~~~~~~~~~~~~~~~~ a one-line code block ~~~~~~~~~~~~~~~~~~~~~
默认情况下，输出与普通代码块相同。
对于 Doxygen 支持的语言，您还可以使代码块以语法高亮显示。为此，您需要在开头围栏后指明与编程语言对应的典型文件扩展名。例如，要根据 Python 语言进行高亮显示，您需要编写以下内容：
~~~~~~~~~~~~~{.py}
# A class
class Dummy:
pass
~~~~~~~~~~~~~
这将产生
对于 C，您会这样写
~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~
这将产生
点是可选的，当语言名称以字母字符开头且后续字符为字母数字字符或加号时，花括号是可选的。
另一种表示围栏代码块的方法是使用 3 个或更多反引号 (```)
对于图片格式 dot、msc 和 plantuml，只要图片格式启用（参见 HAVE_DOT 和 PLANTUML_JAR_PATH），围栏块将显示为图片，否则显示为纯代码。
示例
或
标准 Markdown 不支持给标题加标签，如果想要链接到某个章节，这将是一个问题。
PHP Markdown Extra 允许您通过向标题添加以下内容来标记标题：
Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
要链接到同一注释块中的某个章节，您可以使用
[Link text](#labelid)
通常，要链接到某个章节，Doxygen 允许您使用 @ref。
[Link text](@ref labelid)
请注意，这仅适用于级别 1 到 4 的标题。
标准 Markdown 不支持控制图像尺寸，这导致在编写文档时灵活性较低。
PHP Markdown Extra 允许您向图像添加额外的属性，例如
{attributes}
为了支持针对输出格式的特定属性，支持以下语法
{format: attributes, format: attributes}
有关可能性的描述，请参阅 \image 命令的 尺寸指示 段落。
例如
{html: width=50%, latex: width=5cm}
尽管 Doxygen 尽可能地遵循 Markdown 标准，但仍有一些偏差和 Doxygen 特有的补充。
Doxygen 可以处理 Markdown 格式的文件。为此，此类文件的扩展名应为 .md 或 .markdown（如果您的 Markdown 文件具有不同的扩展名，请参阅 EXTENSION_MAPPING，并将解析器名称设置为 md）。每个文件都将转换为一个页面（有关详细信息，请参阅 page 命令）。如果 Markdown 文件以专用命令（例如 \defgroup、\dir）开头，Doxygen 将不会创建专用页面，以避免在文件仅包含目录或组文档时创建空页面。子目录中的 README.md 文件将被视为目录文档，除非它被专用命令（例如 @page、@mainpage）明确覆盖以创建新页面。
默认情况下，页面的名称和标题派生自文件名。但是，如果文件以一级标题开头，则将其用作页面的标题。如果您为标题指定标签（如标题 ID 属性中所示），Doxygen 将使用该标签作为页面名称。
如果标签名为 index 或 mainpage，Doxygen 会将文档放在首页 (index.html) 上。
以下是一个文件 README.md 的示例，它在 Doxygen 处理后将显示为主页。
My Main Page {#mainpage}
============
Documentation that will appear on the main page
如果一个页面有标签，您可以使用 @ref 链接到它，如上所示。要引用一个没有此类标签的 Markdown 页面，您只需使用该页面的文件名，例如
See [the other page](other.md) for more info.
Markdown 对块级 HTML 的处理方式非常严格。
块级 HTML 元素，例如 <div>、<table>、<pre>、<p> 等，必须与周围内容用空行分隔，并且块的开始和结束标签不应使用制表符或空格缩进。
Doxygen 没有此要求，并且也会在此类 HTML 块内处理 Markdown 格式。唯一的例外是 <pre> 块，它们将未经处理地传递（对于 ASCII 艺术很方便）。
Doxygen 不会处理逐字或代码块中的 Markdown 格式，以及其他需要不加修改地处理的部分（例如公式或内联点图）。
Markdown 允许使用单个制表符或 4 个空格来开始代码块。由于 Doxygen 在进行 Markdown 处理之前已经用空格替换了制表符，因此只有在配置文件中的 TAB_SIZE 设置为 4 时，效果才会相同。如果设置为更高的值，代码块中将出现空格。更低的值将阻止单个制表符被解释为代码块的开始。
使用 Markdown，任何缩进 4 个空格（列表内缩进 8 个空格）的块都被视为代码块。此缩进量是绝对的，即从行首开始计算。
由于 Doxygen 注释可以出现在编程语言所需的任何缩进级别，因此它使用相对缩进。缩进量是相对于前一个段落计算的。如果前面没有段落（即您想从代码块开始），则使用整个注释块的最小缩进量作为参考。
在大多数情况下，这种差异不会导致不同的输出。只有当您调整段落缩进时，差异才明显。
text text text code
在这种情况下，Markdown 会将“code”一词放入代码块中，而 Doxygen 会将其视为普通文本，因为尽管绝对缩进是 4，但相对于前一个段落的缩进只有 1。
请注意，在确定相对缩进时，列表标记不计算在内。
1. Item1
More text for item1
2. Item2
Code block for item2
对于 Item1，缩进为 4（将列表标记视为空格时），因此下一个段落“More text...”以相同的缩进级别开始，因此不被视为代码块。
与标准 Markdown 和 GitHub Flavored Markdown 不同，Doxygen 不会触及内部的下划线、星号或波浪号，因此以下内容将按原样显示
a_nice_identifier
此外，* 或 _ 仅在以下情况下开始强调，而 ~ 仅在以下情况下开始删除线：
强调或删除线在以下情况下结束：
强调或删除线的范围仅限于单个段落。
最后，请注意，当您想在 C 风格的 Doxygen 注释块（即 /``** ... *``/）中，通过行首的 * 对一段文本进行强调时，如果该注释块没有作为列“对齐”的引导 *，那么 Doxygen 会将行首的 * 序列视为“对齐”而不是强调。因此，以下内容不会渲染为粗体：
/** **this is not bold** */
然而，这将呈现为粗体
/** * **this is bold** */
请注意，与标准 Markdown 不同，Doxygen 不会触及以下内容。
A `cool' word in a `nice' sentence.
换句话说；单引号取消了用一对反引号包裹的代码跨度的特殊处理。添加此额外限制是为了向后兼容。
如果想在代码跨度内使用单引号，请不要使用一个反引号，而是在代码跨度周围使用两个反引号。
同样，双反引号也会被双引号结束。
A ``cool'' word in a ``nice'' sentence.
在 Markdown 中，两个由空行分隔的列表会合并成一个列表，这可能相当出乎意料，许多人认为这是一个 bug。然而，Doxygen 会按照您的预期创建两个独立的列表。
示例
- Item1 of list 1 - Item2 of list 1 1. Item1 of list 2 2. Item2 of list 2
在 Markdown 中，您用来标记列表的实际数字对 Markdown 生成的 HTML 输出没有影响。也就是说，标准 Markdown 将以下内容视为一个包含 3 个编号项的列表：
1. Item1 1. Item2 1. Item3
然而，Doxygen 要求用作标记的数字严格按升序排列，因此上述示例将生成 3 个列表，每个列表包含一个项目。项目编号与前一个项目编号相等或更低的项目将开始一个新的列表。例如：
1. Item1 of list 1 3. Item2 of list 1 2. Item1 of list 2 4. Item2 of list 2
将产生
历史上，Doxygen 还有另一种创建编号列表的方式，即使用 -# 标记。
-# item1 -# item2
带有选中或未选中复选框指示符的列表，通过使用 - [ ] 或 - [x] 或 - [X] 作为标记来创建。
- [ ] unchecked - [x] checked
在注释块中使用星号 (*) 来开始列表或创建分隔线时，需要特别注意。
Doxygen 会在进行 Markdown 处理之前从注释中去除任何前导星号。因此，虽然以下代码运行良好：
/** A list:
* * item1
* * item2
*/
当您删除前导星号时，Doxygen 也会删除其他星号，使列表消失！
用星号创建的标尺将完全不可见。它们只在 Markdown 文件中有效。
为了避免零散的 * 或 _ 与许多段落之后的内容匹配，并显示中间的所有内容都带有强调，Doxygen 将 * 和 _ 的范围限制为单个段落。
对于代码跨度，在开始和结束反引号之间只允许有两个换行符。
链接也有限制；链接文本和链接标题各只能包含一个换行符，URL 不能包含任何换行符。
在 GitHub 版本的 Markdown 中，支持所谓的警报，其语法类似于一级块引用后跟 [!<alert>]，其中 <alert> 可以是 note、warning、tip、caution 或 important 中的一个。在 Doxygen 中，这些警报被翻译成普通的 Doxygen 命令。
示例
这将呈现为
当 Doxygen 解析源代码时，它首先提取注释块，然后将这些块传递给 Markdown 预处理器。Markdown 预处理器的输出包含带有 特殊命令和 HTML 命令的文本。第二次处理将 Markdown 预处理器的输出转换为各种输出格式。
在 Markdown 预处理期间不会产生错误。任何不符合 Markdown 语法的都会按原样传递。在随后的解析阶段，这可能会导致错误，这些错误可能并不总是显而易见的，因为它们基于中间格式。
要查看 Markdown 处理后的结果，您可以使用 -d Markdown 选项运行 Doxygen。然后，它将打印每个注释块在 Markdown 处理之前和之后的内容。
1.15.0 生成