自Doxygen 版本1.8.0，Markdown被引进。
接下来，我们将先简单介绍标准的Markdown语法，读者可以进入Markdown官网查询更详细的细节。然后讨论一下Doxygen支持的Markdown扩展，最后讨论一下Doxygen对Markdown标准的实现细节。

Standard Markdown

Paragraphs

实际上甚至在Doxygen支持Markdown之前，它处理段落的方式与Markdown如出一辙：为了生成一个段落，只需在两个连续的行间加至少一个空行即可。
例如：

Here is text for one paragraph.We continue with more text in another paragraph.

Headers

就像Markdown一样，doxygen支持两种形式的标题。Level 1或者2标题可以通过一下形式生成：

This is a level 1 header
========================This is a level 2 header
------------------------

每个标题后紧跟着包含‘=’与’-‘的一行。‘=’或者’-‘的数量是不重要的，只要他们至少两个即可。

你也可以在一行的开始使用’#’。‘#’的数量决定了标题的层次（最终支持6层).你可以通过任意数量(包含0）的’#’结束标题。

例如：

# This is a level 1 header### This is level 3 header #######

Block quotes

我们可以通过在一行的开始键入1个或者多个’>’创建块引用。
如下：

> This is a block quote
> spanning multiple lines

列表和代码可以出现在块引用中。块引用也支持嵌套使用。

注意：Doxygen要求我们在最后一个’>’后空一格才能开始写其他的字符。
例如：

>  if OK\n
>1 if NOK

第二行并不能被视作一个 block quote.

Lists

一些简单的列表可以以-,+,*开头。

- Item 1More text for this item.- Item 2+ nested list item.+ another nested item.
- Item 3

效果为：

• Item 1

  More text for this item.

• Item 2

  • nested list item.
  • another nested item.
• Item 3

也有数字列表，如下：

1. First item.
2. Second item.

Code Blocks

在两个正常的段落中插入一段代码，只需要将每行代码开头，留至少4个空格

This a normal paragraphThis is a code blockWe continue with a normal paragraph again.

Doxygen将移出对代码块的强制识别。注意：我们也不能在段落中间开始代码块，即代码块与上一句之间必须空一行。

Horizontal Rulers

可以通过至少3个*,-, _产生水平参考线。

例如：

- - -
***
______

效果为：

---

---

---

Emphasis

斜体，使用一个*或者_.
黑体，使用两个*或者_.
例如：

 *single asterisks*_single underscores_**double asterisks**__double underscores__

效果:
single asterisks

single underscores

double asterisks

double underscores

code spans

为了揭示代码的范围，你需要使用(`)括起来。不像代码块，code spans可以出现在一个段落里。例如：

Use the `printf()` function.

Links

Doxygen支持两种形式的链接：inline and reference.
两种形式的链接都以[链接文本]开始。

Inline Links

对于 inline link，文本后直接跟着一个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) 

Reference Links

不同于Inline Links直接将URL放在内部，你也可以将定义一个link与将其指向一个文本分开。
例如：

[link name]: http://www.example.com "Optional title"

以上”Optional title”也可以改为：

(Optional title)
‘Optional title’

一旦定义好, 链接看起来如下:

[link text][link name]

如果link text 和 link name 是相同的, 也可以

[link name][]

or even

[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"

Link definitions（即” “里的内容）将不会出现在结果中。

也支持内部链接，如下：

[myclass]: @ref MyClass "My class"

Images

Markdown 关于images 的语法类似于links. 唯一的区别是在link text前加了一个!

例如：

![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 to link to an image:

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

The caption text is optional.

Automatic Linking

为了支持URL or e-mail address的链接， Markdown 支持如下语法:

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

注意 : doxygen在没有尖括号时，也可以产生Links.

Markdown Extensions

Table of Contents

Doxygen可以使用 [TOC] 来添加章节目录。

注意： [TOC] 等价于 \tableofcontents .

Tables

直接看例子：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell 
Content Cell  | Content Cell 

效果：

列对齐可以控制通过在分割线两头添加一个或两个冒号。
例如：

| Right | Center | Left  |
| ----: | :----: | :---- |
| 10    | 10     | 10    |
| 1000  | 1000   | 1000  |

效果：

Fenced Code Blocks

一个带围栏的code block不要求能识别代码。它可以通过一对”fence lines”定义。一行中至少3个(~).开头和结尾有相同数量的波浪线。
如下：

This is a paragraph introducing:~~~~~~~~~~~~~~~~~~~~~
a one-line code block
~~~~~~~~~~~~~~~~~~~~~

默认输出和 normal code block相同。

对于Doxygen支持的语言，我们也可以通过标明后缀名来实现语法高亮。例如：对于python

~~~~~~~~~~~~~{.py}
# A class
class Dummy:
    pass
~~~~~~~~~~~~~

效果：

对于C，有：

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

效果:

也可以通过至少3个引号(`)来表明代码块。

Header Id Attributes

标准的Markdown不支持标记标题，但是当你想要链接一个章节时，便会出现错误。

PHP Markdown额外支持标记标题，如下：

Header 1                {#labelid}
========## Header 2 ##          {#labelid2}

为了链接章节，只需要:

  [Link text](#labelid)

你也可以使用@ref

  [Link text](@ref labelid)

注意;以上仅支持Level1 to 4.

Doxygen specifics

Including Markdown files as pages

如果标题的标签为index or mainpage， doxygen 将会把它放在首页 (index.html).

Here is an example of a file README.md that will appear as the main page when processed by doxygen:

My Main Page                         {#mainpage}
============

如果a page有一个标签，你可以使用@ref来链接它。
当然了，如果不使用标签来链接a markdown page，你也可以直接使用文件名，如下：

See [the other page](other.md) for more info.

效果:
See the other page for more info.