Markdown サポートは Doxygen バージョン 1.8.0 で導入されました。これは John Gruber によって書かれたプレーンテキストの書式設定構文で、以下の基本設計目標があります
Markdown の書式設定構文の設計目標は、可能な限り読みやすくすることです。Markdown 形式のドキュメントは、タグや書式設定命令でマークアップされているように見えず、プレーンテキストとしてそのまま公開できるという考え方です。Markdown の構文は既存のいくつかのテキスト-HTML フィルターの影響を受けていますが、Markdown の構文の最大のインスピレーション源は、プレーンテキストの電子メールの形式です。
次のセクションでは、標準の Markdown 機能について簡単に説明します。詳細については、Markdown サイトを参照してください。
PHP Markdown Extra や GitHub flavored Markdown など、いくつかの機能強化が行われました。Markdown 拡張機能セクションでは、Doxygen がサポートする拡張機能について説明します。
最後に、セクション Doxygen の特定事項 では、Markdown 標準の Doxygen の実装に関するいくつかの特定事項について説明します。
Doxygen が Markdown サポートを持つ以前から、Markdown と同じ段落処理方法をサポートしていました。段落を作成するには、連続するテキスト行を1つ以上の空白行で区切るだけです。
例
Here is text for one paragraph. We continue with more text in another paragraph.
Markdown と同様に、Doxygen は2種類の見出しをサポートしています
レベル1または2の見出しは、次のように作成できます
This is a level 1 header ======================== This is a level 2 header ------------------------
見出しの後には、='s または -'s のみが含まれる行が続きます。='s または -'s の正確な量は、少なくとも2つあれば重要ではありません。
あるいは、行の先頭に #'s を使用して見出しを作成することもできます。行の先頭にある #'s の数がレベルを決定します（最大6レベルまでサポート）。#'s の数は任意で、見出しを終了することができます。
以下に例を示します
# This is a level 1 header ### This is level 3 header #######
引用ブロックは、テキストのみの電子メールで使用される方法と同様に、各行を1つ以上の >'s で開始することで作成できます。
> This is a block quote > spanning multiple lines
リストとコードブロック（下記参照）は引用ブロック内に表示できます。引用ブロックはネストすることもできます。
Doxygen では、誤検出を避けるため、（最後の）> 文字の後にスペースを入れる必要があることに注意してください。つまり、以下のように記述した場合、
0 if OK\n >1 if NOK
2行目は引用ブロックとして認識されません。
単純な箇条書きリストは、行を -, +, または * で開始することで作成できます。
- 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 とは若干異なるため、セクション コードブロックのインデント を参照してください。
少なくとも3つ以上のハイフン、アスタリスク、またはアンダースコアを含む行には、水平線が生成されます。行には任意の量の空白を含めることもできます。
例
- - - ______
コメントブロックでアスタリスクを使用しても機能しないことに注意してください。詳細については、アスタリスクの使用 を参照してください。
ハイフンを使用し、前の行が空ではない場合、ハイフンのシーケンスに少なくとも1つの空白を使用する必要があることに注意してください。そうしないと、レベル2の見出しとして認識される可能性があります（見出し を参照）。
テキストフラグメントを強調するには、フラグメントをアンダースコアまたはスターで開始および終了します。2つのスターまたはアンダースコアを使用すると、強い強調が生成されます。3つのスターまたはアンダースコアは、前の2つのオプションの強調を組み合わせます。
例
*single asterisks* _single underscores_ **double asterisks** __double underscores__ ***triple asterisks*** ___triple underscores___
Doxygen が強調/打ち消し線スパンを標準/Markdown GitHub Flavored Markdown とは若干異なる方法で処理する方法については、セクション 強調と打ち消し線の制限 を参照してください。
テキストフラグメントに打ち消し線を引くには、フラグメントを2つのチルダで開始および終了します。
例
~~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 コマンドを使用することと同じであることに注意してください。
\tableofcontents を使用する際、Markdown ヘッダー を使用している場合に目次が表示されないことを避けるため、TOC_INCLUDE_HEADINGS を0より大きい値に設定する必要があることに注意してください。
"Markdown Extra" で定義されている機能の1つは、シンプルなテーブル のサポートです。
テーブルは、ヘッダー行、区切り行、および少なくとも1つの行行で構成されます。テーブルの列はパイプ (|) 文字で区切られます。
以下に例を示します
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
これにより、次のテーブルが生成されます。
| 最初のヘッダー | 2番目のヘッダー |
|---|---|
| コンテンツセル | コンテンツセル |
| コンテンツセル | コンテンツセル |
列の配置は、ヘッダー区切り行の1つまたは2つのコロンで制御できます。
| 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 |
列スパンは、隣接する垂直バー ("|") を使用してサポートされます。追加の垂直バーごとに、追加の列がスパンされることを示します。言い換えれば、単一の垂直バーは単一の列スパンを示し、2つの垂直バーは2列スパンを示し、などです。例
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 |||
次のように表示されます
| 右 | 中央 | 左 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | ||
Doxygen のより複雑なテーブルについては、テーブルの含め方 を参照してください。
"Markdown Extra" で定義されているもう1つの機能は、フェンス付きコードブロック のサポートです。
フェンス付きコードブロックはインデントを必要とせず、「フェンスライン」のペアによって定義されます。このような行は、行に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; }
~~~~~~~~~~~~~~~
これは以下を生成します
ドットはオプションであり、言語名がアルファベット文字で始まり、それ以降の文字が英数字またはプラス記号である場合、中括弧はオプションです。
フェンス付きコードブロックを示すもう1つの方法は、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 コマンドを参照してください）。Doxygen は、Markdown ファイルが専用コマンド（例: \defgroup、\dir）で始まる場合、専用ページを作成しません。これは、ファイルがディレクトリまたはグループのドキュメントのみを含む場合に空のページが作成されるのを避けるためです。サブディレクトリ内の README.md ファイルは、新しいページを作成するための専用コマンド（例: @page、@mainpage）によって明示的に上書きされない限り、ディレクトリドキュメントとして扱われます。
デフォルトでは、ページの名前とタイトルはファイル名から派生します。ただし、ファイルがレベル1のヘッダーで始まる場合、それがページのタイトルとして使用されます。ヘッダーにラベルを指定した場合（ヘッダー ID 属性 で示されているように）、Doxygen はそれをページ名として使用します。
ラベルが index または mainpage と呼ばれる場合、Doxygen はドキュメントをフロントページ (index.html) に配置します。
以下は、Doxygen で処理されたときにメインページとして表示される README.md ファイルの例です。
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 は、逐語的ブロックやコードブロック、および変更なしで処理する必要があるその他のセクション（たとえば、数式やインラインのドットグラフ）内では 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.
言い換えれば、単一引用符は、バッククォートのペアで囲まれたコードスパンの特殊な処理をキャンセルします。この追加の制限は、後方互換性のために追加されました。
コードスパン内にシングルクォートを含めたい場合は、コードスパンの周囲に1つのバッククォートではなく、2つのバッククォートを使用してください。
Markdown では、空行で区切られた2つのリストは1つのリストに結合されますが、これは非常に予期しない動作であり、多くの人がバグだと考えています。しかし Doxygen は、期待どおりに2つの別々のリストを作成します。
例
- Item1 of list 1 - Item2 of list 1 1. Item1 of list 2 2. Item2 of list 2
Markdown では、リストをマークするために使用する実際の数字は、Markdown が生成する HTML 出力に影響を与えません。つまり、標準 Markdown は以下を3つの番号付き項目を持つ1つのリストとして扱います。
1. Item1 1. Item2 1. Item3
しかし、Doxygen はマークとして使用される数字が厳密に昇順であることを要求するため、上記の例では1つの項目を持つ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 は * と _ の範囲を単一の段落に制限しています。
コードスパンの場合、開始と終了のバッククォートの間には、2つまでの改行しか許可されません。
リンクにも制限があります。リンクテキストとリンクタイトルはそれぞれ1つの改行しか含めることができず、URLには改行を含めることはできません。
GitHub 版の Markdown には、いわゆるアラートのサポートがあり、構文は1レベルの引用ブロックに [!<alert>] が続く形式で、<alert> は note、warning、tip、caution、または important のいずれかです。Doxygen では、これらのアラートは通常の Doxygen コマンドに変換されます。
例
これは次のようにレンダリングされます
Doxygen がソースコードを解析する際、まずコメントブロックを抽出し、それらを Markdown プリプロセッサに渡します。Markdown プリプロセッシングの出力は、特殊コマンド と HTML コマンド を含むテキストで構成されます。2回目のパスでは、Markdown プリプロセッサの出力を取得し、さまざまな出力形式に変換します。
Markdown プリプロセッシング中にはエラーは発生しません。Markdown 構文に適合しないものはすべてそのまま渡されます。その後の解析フェーズでは、これがエラーにつながる可能性があり、中間形式に基づいているため、常に明白ではない場合があります。
Markdown 処理後の結果を見るには、-d Markdown オプションを付けて Doxygen を実行できます。これにより、各コメントブロックが Markdown 処理の前後に表示されます。
1.14.0