Markdown 格式語法的設計目標是使其盡可能易於閱讀。其理念是，一個 Markdown 格式的文件應該可以原樣發布為純文字，而不會看起來像是被標籤或格式指令標記過。雖然 Markdown 的語法受到了幾個現有的 text-to-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
------------------------

標題後面跟著一行僅包含 ='s 或 -'s 的行。請注意，只要至少有兩個，='s 或 -'s 的確切數量並不重要。

或者，您可以在一行的開頭使用 #'s 來建立標題。行首 #'s 的數量決定了層級（支援最多 6 個層級）。您可以使用任意數量的 #'s 來結束標題。

以下是一個範例

# This is a level 1 header

### This is level 3 header #######

區塊引言

區塊引言可以透過以一個或多個 >'s 開頭每行來建立，類似於純文字電子郵件中使用的方式。

> 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.dev.org.tw/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> 等，必須以空白行與周圍內容分隔，並且區塊的開始和結束標籤不應以 Tab 或空格縮排。

Doxygen 沒有此要求，並且也會處理此類 HTML 區塊內的 Markdown 格式。唯一的例外是 <pre> 區塊，它們會被原封不動地傳遞（對於 ASCII 圖形非常方便）。

Doxygen 不會處理逐字或程式碼區塊內的 Markdown 格式，以及其他需要不經修改處理的區段（例如公式或內嵌 dot 圖形）。

程式碼區塊縮排

Markdown 允許使用單個 Tab 或 4 個空格來開始程式碼區塊。由於 Doxygen 在執行 Markdown 處理之前已將 Tab 替換為空格，因此只有在組態檔案中的 TAB_SIZE 設定為 4 時，效果才會相同。當其設定為較高的值時，空格會出現在程式碼區塊中。較低的值會阻止將單個 Tab 解譯為程式碼區塊的開頭。

使用 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

對於項目 1，縮排為 4（在將清單標記視為空白時），因此下一個段落「更多文字...」從相同的縮排層級開始，因此不會被視為程式碼區塊。

強調和刪除線的限制

與標準 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 警示

在 Markdown 的 GitHub 版本中，支援所謂的警示，其語法類似於一級區塊引號後接 [!<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 警示

除錯問題