自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.