Markdown 格式语法的目标是使其尽可能易读。其理念是，Markdown 格式的文档应该可以按原样作为纯文本发布，而不会看起来像是用标签或格式指令标记的。虽然 Markdown 的语法受到了几个现有文本到 HTML 过滤器的影响，但 Markdown 语法最大的灵感来源是纯文本电子邮件的格式。

在下一节中，将简要讨论标准 Markdown 的功能。读者可以参考Markdown 网站了解更多详细信息。

进行了一些增强，例如PHP Markdown Extra和GitHub flavored Markdown。Markdown 扩展部分讨论了 Doxygen 支持的扩展。

最后，Doxygen 特性部分讨论了 Doxygen 对 Markdown 标准的实现的一些具体细节。

标准 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__

有关 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](/path/to/img.jpg)
![Caption text](/path/to/img.jpg "Image title")
![Caption text][img def]
![img def]

[img def]: /path/to/img.jpg "Optional Title"

在这里，您也可以使用 @ref 链接到图片

![Caption text](@ref image.png)
![img def]

[img def]: @ref image.png "Caption text"

标题文本是可选的。

注意: 不要忘记将图片的路径添加到 IMAGE_PATH 中。

自动链接

要创建指向 URL 或电子邮件地址的链接，Markdown 支持以下语法

<http://www.example.com>
<https://www.example.com>
<ftp://www.example.com>
<mailto:[email protected]>
<[email protected]>

请注意，Doxygen 还将在没有尖括号的情况下生成链接。

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
10	1000	1000

通过直接相邻的竖线 ("|") 支持列跨度。每个额外的竖线表示要跨越的额外列。换句话说，单个竖线表示单个列跨度，两个竖线表示 2 列跨度，依此类推。例如

| 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
~~~~~~~~~~~~~

这将产生

# 一个类
class Dummy
    pass

对于 C 语言，您将编写

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

这将产生

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

点号是可选的，当语言名称以字母字符开头且后续字符为字母数字字符时，花括号是可选的。

表示围栏代码块的另一种方法是使用 3 个或更多个反引号 (```)

```
也是一个围栏代码块
```

对于图像格式 dot、msc 和 plantuml，如果启用了图像格式（请参阅 HAVE_DOT 和 PLANTUML_JAR_PATH），则围栏块将显示为图像，否则将显示为纯代码。

示例

```plantuml
Alice -> Bob
```

或

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

标题 ID 属性

标准 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 允许您像这样向图像添加额外的属性

![Caption text](/path/to/img.jpg){attributes}

为了允许输出格式特定的属性，支持以下语法

![Caption text](/path/to/img.jpg){format: attributes, format: attributes}

有关可能性的描述，请参阅尺寸指示段落，了解 \image 命令。

例如

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

Doxygen 规范

尽管 Doxygen 尝试尽可能遵循 Markdown 标准，但还是有一些偏差和 Doxygen 特定的补充。

将 Markdown 文件作为页面包含

Doxygen 可以处理具有 Markdown 格式的文件。为此，此类文件的扩展名应为 .md 或 .markdown（如果您的 Markdown 文件具有不同的扩展名，请参阅 EXTENSION_MAPPING，并使用 md 作为解析器的名称）。每个文件都会转换为一个页面（有关详细信息，请参阅 page 命令）。

默认情况下，页面的名称和标题派生自文件名。但是，如果文件以 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.

HTML 块的处理

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.

换句话说，单引号会取消对用一对反引号字符包裹的代码跨度的特殊处理。添加此额外限制是为了向后兼容。

如果您想在代码跨度内包含单引号，请不要使用一个反引号，而是在代码跨度周围使用两个反引号。

列表扩展

使用 Markdown 时，由空行分隔的两个列表会连接在一起形成一个列表，这可能会让人感到意外，许多人认为这是一个错误。但是，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

将产生

列表 1 的项 1
列表 1 的项 2

列表 2 的项 1
列表 2 的项 2

历史上，Doxygen 还有另一种通过使用 -# 标记来创建编号列表的方法

-# item1
-# item2

带有选中或未选中复选框指示器的列表使用 - [ ] 或 - [x] 或 - [X] 作为标记

- [ ] unchecked
- [x] checked

星号的使用

在注释块中使用 * 来开始列表或创建标尺时，必须格外小心。

Doxygen 会在进行 Markdown 处理之前从注释中删除任何前导 *。因此，尽管以下内容可以正常工作

    /** A list:
     *  * item1
     *  * item2
     */

当您删除前导 * 时，Doxygen 也会删除其他星号，从而使列表消失！

用 * 创建的标尺将根本不可见。它们仅在 Markdown 文件中有效。

标记范围的限制

为了避免不小心使用 * 或 _ 匹配到很多段落后的内容，并显示中间的所有内容，Doxygen 将 * 和 _ 的范围限制为单个段落。

对于代码跨度，在开始和结束反引号之间仅允许两个新行。

链接也有一些限制；链接文本和链接标题各自只能包含一个新行，URL 不能包含任何新行。

支持 GitHub 警报

在 GitHub 版本的 Markdown 中，有所谓的警告框支持，其语法类似于一级块引用，后跟 [!<alert>]，其中 <alert> 可以是 note、warning、tip、caution 或 important 中的一个。在 Doxygen 中，这些警告框会被转换为普通的 Doxygen 命令。

> [!note] 会被转换为 \note
> [!warning] 会被转换为 \warning
> [!tip] 会被转换为 \remark
> [!caution] 会被转换为 \attention
> [!important] 会被转换为 \important

示例

> [!note]

> 注释的特殊文本 for

这将呈现为

注意: 注释的特殊文本

调试问题

当 Doxygen 解析源代码时，它首先提取注释块，然后将它们传递给 Markdown 预处理器。Markdown 预处理的输出包含带有特殊命令和 HTML 命令的文本。第二遍处理会获取 Markdown 预处理器的输出，并将其转换为各种输出格式。

在 Markdown 预处理期间不会产生错误。任何不符合 Markdown 语法的都会按原样传递。在随后的解析阶段，这可能会导致错误，这些错误可能并不总是很明显，因为它们基于中间格式。

要查看 Markdown 处理后的结果，可以使用 -d Markdown 选项运行 Doxygen。然后，它将打印 Markdown 处理前后的每个注释块。

转到下一节或返回索引。

目录

标准 Markdown

段落

标题

块引用

列表

代码块

水平线

强调

删除线

代码片段

链接

行内链接

引用链接

图片

自动链接

Markdown 扩展

目录

表格

围栏代码块

标题 ID 属性

图像属性

Doxygen 规范

将 Markdown 文件作为页面包含

HTML 块的处理

代码块缩进

强调和删除线限制

代码跨度限制

列表扩展

星号的使用

标记范围的限制

支持 GitHub 警报

调试问题