‍Markdown の書式構文の設計目標は、可能な限り読みやすくすることです。Markdown 形式のドキュメントは、タグや書式設定の指示でマークアップされているように見えずに、プレーンテキストとしてそのまま公開できるべきであるという考え方です。Markdown の構文は、既存の複数の text-to-HTML フィルターの影響を受けていますが、Markdown の構文の最大のインスピレーションの源は、プレーンテキストメールの形式です。

次のセクションでは、標準 Markdown の機能について簡単に説明します。詳細については、Markdown サイトを参照してください。

PHP Markdown Extra や GitHub flavored Markdown など、いくつかの機能拡張が行われました。「Markdown 拡張機能」のセクションでは、Doxygen がサポートする拡張機能について説明します。

最後の「Doxygen 固有の仕様」のセクションでは、Doxygen の Markdown 標準の実装に関するいくつかの固有の仕様について説明します。

標準 Markdown

段落

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

ヘッダーの後に、= または - のみを含む行が続きます。= または - の正確な数は重要ではありませんが、少なくとも 2 つ以上が必要です。

または、行の先頭に # を使用してヘッダーを作成することもできます。行の先頭にある # の数によってレベルが決まります (最大 6 レベルまでサポートされています)。ヘッダーは任意の数の # で終了できます。

例を示します

# This is a level 1 header

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

引用

引用は、テキストのみのメールで使用されているものと同様に、各行を 1 つ以上の > で始めることで作成できます。

> This is a block quote
> spanning multiple lines

リストとコードブロック (下記参照) は、引用ブロック内に表示できます。引用ブロックはネストすることもできます。

Doxygen では、誤検出を避けるために、(最後の) > 文字の後にスペースを入れる必要があります。つまり、次のように記述した場合

0  if OK\n
>1 if NOK

2 行目は引用として認識されません。

コードブロック

整形済みベタ打ちブロックは、テキストブロック内の各行を少なくとも 4 つの追加スペースでインデントすることで作成できます。

This a normal paragraph

    This is a code block

We continue with a normal paragraph again.

Doxygen は、コードブロックから必須のインデントを削除します。段落の途中でコードブロックを開始することはできません (つまり、コードブロックの前の行は空である必要があります)。

Doxygen がインデントをどのように処理するかについての詳細は、「コードブロックのインデント」のセクションを参照してください。これは標準 Markdown とは少し異なります。

水平線

3 つ以上のハイフン、アスタリスク、またはアンダースコアを含む行に対して、水平線が生成されます。行には任意の量の空白を含めることもできます。

例

- - -
______

コメントブロックでアスタリスクを使用しても機能しないことに注意してください。「アスタリスクの使用」で詳細をご覧ください。
ハイフンを使用し、前の行が空でない場合は、ハイフンのシーケンスで少なくとも 1 つの空白を使用する必要があります。そうしないと、レベル 2 ヘッダーと見なされる可能性があります (ヘッダーを参照)。

強調

テキストフラグメントを強調するには、フラグメントをアンダースコアまたはアスタリスクで囲みます。2 つのアスタリスクまたはアンダースコアを使用すると、強い強調が生成されます。

例

 *single asterisks*

 _single underscores_

 **double asterisks**

 __double 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](/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」で定義されている機能の 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
10	1000	1000

列スパンは、直接隣接する縦棒 ("|") によってサポートされています。追加の縦棒はそれぞれ、スパンされる追加の列を示します。言い換えれば、単一の縦棒は単一の列スパンを示し、2 つの縦棒は 2 列のスパンを示します。例

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

次のようになります

右	中央	左
10	10	10
1000

Doxygen のより複雑な表については、「表を含める」をご覧ください

フェンス付きコードブロック

「Markdown Extra」で定義されているもう 1 つの機能は、フェンス付きコードブロックのサポートです

フェンス付きコードブロックはインデントを必要とせず、「フェンス線」のペアによって定義されます。このような行は、1 行に 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.dokyumento.jp/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) に配置します。

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.

HTML ブロックの扱い

Markdown は、ブロックレベル HTML の処理方法において非常に厳格です

‍ブロックレベル HTML 要素 (例: <div>、<table>、<pre>、<p> など) は、空白行で周囲のコンテンツから分離する必要があり、ブロックの開始タグと終了タグはタブまたはスペースでインデントしないでください。

Doxygen にはこの要件はなく、そのような HTML ブロック内で Markdown 形式も処理します。唯一の例外は <pre> ブロックで、これは変更されずに渡されます (ASCII アートに便利です)。

Doxygen は、逐語的またはコードブロック内、および変更なしで処理する必要がある他のセクション (たとえば、数式やインライン dot グラフ) 内では 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 コメントブロック (つまり /** ... */) 内の * を使用して、行の先頭にあるテキストの一部を強調表示したい場合、先頭に列「lineup」として * がない場合、Doxygen は行の先頭にある * のシーケンスを「lineup」として認識し、強調表示としては認識しません。したがって、次は太字としてレンダリングされません

/**
 **this is not bold**
 */

ただし、これは太字としてレンダリングされます

/**
 * **this is bold**
 */

コードスパンの制限

標準 Markdown とは異なり、Doxygen は次をそのままにすることに注意してください。言い換えれば、単一引用符は、バッククォート文字のペアで囲まれたコードスパンの特別な処理をキャンセルします。この追加の制限は、下位互換性のために追加されました。コードスパン内に単一引用符を含める場合は、1 つのバッククォートではなく、コードスパンの周りに 2 つのバッククォートを使用してください。

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

次を生成します

リスト 1 の項目 1
リスト 1 の項目 2

リスト 2 の項目 1
リスト 2 の項目 2

歴史的に、Doxygen には -# マーカーを使用して番号付きリストを作成する追加の方法があります

-# item1
-# item2

チェックボックスがオンまたはオフになっているインジケーターとしてのリストは、- [ ] または - [x] または - [X] をマーカーとして使用します

- [ ] unchecked
- [x] checked

アスタリスクの使用

コメントブロックで * を使用してリストを開始したり、ルーラーを作成したりする場合は、特別な注意が必要です。Doxygen は、Markdown 処理を実行する前に、コメントから先頭の * をすべて削除します。したがって、次は正常に機能しますが

Doxygen は、Markdown 処理を実行する前に、コメントから先頭の * をすべて削除します。したがって、次は正常に機能しますが

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

先頭の * を削除すると、Doxygen は他のアスタリスクも削除し、リストを非表示にします!

* で作成されたルーラーはまったく表示されません。これらは Markdown ファイルでのみ機能します。

マークアップのスコープの制限

迷子の * または _ が数段落後のものと一致し、その間のすべてを強調表示で表示することを避けるために、Doxygen は * と _ のスコープを単一の段落に制限します。コードスパンの場合、開始バッククォートと終了バッククォートの間では、最大 2 つの改行のみが許可されます。リンクにも制限があります。リンクテキストとリンクタイトルはそれぞれ 1 つの改行のみを含めることができ、URL には改行を含めることはできません。

コードスパンの場合、開始バッククォートと終了バッククォートの間では、最大 2 つの改行のみが許可されます。

リンクにも制限があります。リンクテキストとリンクタイトルはそれぞれ 1 つの改行のみを含めることができ、URL には改行を含めることはできません。

GitHub Alerts のサポート

GitHub バージョンの markdown では、いわゆるアラートのサポートがあります。構文は、1 レベルの引用に [!<alert>] が続くものと似ています。<alert> は、note、warning、tip、caution、または important のいずれかになります。Doxygen では、これらのアラートは通常の Doxygen コマンドに変換されます

> [!note] は \note に変換されます
> [!warning] は \warning に変換されます
> [!tip] は \remark に変換されます
> [!caution] は \attention に変換されます
> [!important] は \important に変換されます

例

> [!note]

> ノートの特別なテキスト

次のようにレンダリングされます

注意: ノートの特別なテキスト

デバッグの問題

Doxygen がソースコードを解析するとき、最初にコメントブロックを抽出し、次に Markdown プリプロセッサを介してこれらを渡します。Markdown プリプロセッシングの出力は、特殊コマンドと HTML コマンドを含むテキストで構成されています。2 回目のパスでは、Markdown プリプロセッサの出力を取得し、さまざまな出力形式に変換します。

Markdown プリプロセッシング中にエラーは生成されません。Markdown 構文に適合しないものはすべて、そのまま渡されます。後続の解析フェーズでは、エラーが発生する可能性があります。これらは中間形式に基づいているため、常に明白であるとは限りません。

Markdown 処理後の結果を確認するには、-d Markdown オプションを指定して Doxygen を実行できます。これにより、Markdown 処理の前後の各コメントブロックが出力されます。

次のセクションに進むか、インデックスに戻ります。

目次

標準 Markdown

段落

ヘッダー

引用

リスト

コードブロック

水平線

強調

取り消し線

コードスパン

リンク

インラインリンク

参照リンク

画像

自動リンク

Markdown 拡張機能

目次

表

フェンス付きコードブロック

ヘッダー ID 属性

画像属性

Doxygen 固有の仕様

Markdown ファイルをページとして含める

HTML ブロックの扱い

コードブロックのインデント

強調と取り消し線の制限

コードスパンの制限

リストの拡張機能

アスタリスクの使用

マークアップのスコープの制限

GitHub Alerts のサポート

デバッグの問題