Doxygen 版本 1.8.0 引入了 Markdown 支持。它是由 John Gruber 编写的一种纯文本格式语法，其基本设计目标如下：
Markdown 格式语法的设计目标是使其尽可能地易于阅读。其理念是，Markdown 格式的文档应该能够按原样发布，作为纯文本，而不必看起来像是用标签或格式指令标记过的。虽然 Markdown 的语法受到了几种现有的文本到 HTML 过滤器的影响，但 Markdown 语法的最大灵感来源是纯文本电子邮件的格式。
在下一节中，将简要讨论标准的 Markdown 特性。更多详情请参阅 Markdown 站点。
进行了一些增强，例如 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 支持两种类型的标题
1 级或 2 级标题可以按如下方式创建
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 略有不同。
包含至少三个或更多连字符、星号或下划线的行将生成水平分割线。该行也可以包含任意数量的空白字符。
示例
- - - ______
请注意，在注释块中使用星号不起作用。详情请参阅 星号的使用。
请注意，当使用连字符且前一行不为空时，您必须在连字符序列中使用至少一个空白字符，否则它可能会被视为 2 级标题（参见 标题）。
要强调一段文本，您可以使用下划线或星号开始和结束该片段。使用两个星号或下划线将产生强强调。三个星号或下划线将结合前两种选项的强调。
示例
*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 定义的两种链接创建样式：内联 和 参考。
对于这两种样式，链接定义都以 [方括号] 分隔的链接文本开头。
对于内联链接，链接文本后跟一个 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）明确覆盖以创建新页面。
默认情况下，页面的名称和标题取自文件名。但是，如果文件以 1 级标题开头，则该标题将用作页面标题。如果您为标题指定了标签（如 标题 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 不会处理逐字块或代码块以及其他需要未经更改处理的部分（例如公式或内联 dot 图）中的 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 注释块（即 /** ... */）中通过行首的 *s 来强调一段文本时，如果该注释块没有以 * 作为列的“对齐”，Doxygen 会将行开头的 * 序列视为“对齐”而不是强调。因此，以下内容不会渲染为粗体
/** **this is not bold** */
然而，这会渲染为粗体
/** * **this is bold** */
请注意，与标准 Markdown 不同，Doxygen 会保留以下内容不变。
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 中支持所谓的警示框，其语法类似于一级块引用，后面跟着 [!<警示类型>]，其中 <警示类型> 可以是 note、warning、tip、caution 或 important 中的一个。在 Doxygen 中，这些警示框被转换为普通的 Doxygen 命令
示例
这将渲染为
当 Doxygen 解析源代码时，它首先提取注释块，然后将这些块通过 Markdown 预处理器。Markdown 预处理器的输出是由包含 特殊命令 和 HTML 命令 的文本组成。第二遍将获取 Markdown 预处理器的输出并将其转换为各种输出格式。
在 Markdown 预处理过程中不会产生错误。任何不符合 Markdown 语法的内容都会原样传递。在随后的解析阶段，这可能会导致错误，由于它们基于中间格式，这些错误可能并不总是显而易见的。
要查看 Markdown 处理后的结果，您可以使用 -d Markdown 选项运行 Doxygen。然后，它将打印每个注释块在 Markdown 处理之前和之后的内容。
1.14.0