Azure DevOps で Markdown を使用する

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

この記事では、Azure DevOps の機能と wiki Markdown で Markdown を使用するための基本的な構文ガイダンスについて説明します。 一般的な Markdown 規則 および GitHub フレーバーの拡張機能の両方を使用できます。

Markdown を使用して、書式設定、テーブル、画像などをプロジェクト ページ、README ファイル、ダッシュボード、プル要求、 wiki などを追加します。

すべての Markdown 構文が Azure DevOps のすべての機能でサポートされているわけではありません。 次の表は、この記事の各基本的な構文セクションへのリンクと、それをサポートする機能を示しています。

詳細については、「 完了 (ボード)、 Markdown ウィジェット、 pull request、 README ファイル、および wiki を参照してください。

ヘッダー

ヘッダーを使用してコンテンツを構造化します。 ヘッダーは長いコンテンツをセグメント化し、読みやすくします。

見出しを設定するには、ハッシュ文字 #で行を開始します。 ####など、より多くのハッシュ文字を含む行を開始して、小見出しで解説を整理します。 最大 6 レベルの見出しを使用できます。

例:

# This is a H1 header
## This is a H2 header
### This is a H3 header
#### This is a H4 header
##### This is a H5 header

結果:

段落と改行

サポート対象: 完了の定義 |Markdown ウィジェット |Pull Requests |README ファイル |Wiki

段落または改行に分割して、テキストを読みやすくします。

Pull Request

pull request コメントで、 Enter を選択して改行を挿入し、新しい行にテキストを開始します。

例 - pull request コメント:

Add lines between your text with the **Enter** key.
Your text gets better spaced and makes it easier to read.

結果:

Enter キーを使用してテキスト間に行を追加します。

テキストの間隔が広くなり、読みやすくなります。

Markdown ファイルまたはウィジェット

Markdown ファイルまたはウィジェットで、改行の前に 2 つのスペースを入力し、 Enter を選択して新しい段落を開始します。

例 - Markdown ファイルまたはウィジェット:

Add two spaces before the end of the line, and then select **Enter**.(space, space, Enter)
A space gets added in between paragraphs.

結果:

行の末尾の前に 2 つのスペースを追加し、Enter キーを押します。

段落間にスペースが追加されます。

ブロック引用

前のコメントまたはテキストを引用符で囲み、コメントまたはテキストのコンテキストを設定します。 テキストの 1 行をテキストの前に > 引用符で囲みます。 引用符で囲まれたテキストを入れ子にするには、多数の > 文字を使用します。 複数行にわたって同じレベルの > を使用して、テキスト行のブロックを引用符で囲みます。

例:

> Single line quote
>> Nested quote
>> multiple line
>> quote

結果:

水平ルール

水平ルールを追加するには、一連の破線 ---線を追加します。 ---を含む行の上の行は空白にする必要があります。

例:

above
 
----
below

結果:

上

選択します

強調 (太字、斜体、取り消し線)

サポート対象: 完了の定義 |Markdown ウィジェット |Pull Requests |README ファイル |Wiki

文字に太字、斜体や取り消し線を適用することで、テキストを強調できます。

• 斜体を適用するには: テキストをアスタリスク * またはアンダースコア _ で囲みます
• 太字を適用するには、テキストを 2 つのアスタリスク ** で囲みます。
• 取り消し線を適用するには、テキストを 2 個のチルダ文字 ~~ で囲みます。

これらの要素を組み合わせて、テキストに強調を適用します。

例:

Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~  
**_Bold, italicized text_**  
**~~Bold, strike-through text~~**

結果 :

コメントに 強調 を使用することで、意見の 強さ を表現し、修正 を指摘します
太字、斜体のテキストBold、取り消し線付きテキスト

コードの強調表示

コード強調表示ブロックを使用して、推奨されるコード セグメントを強調表示します。 コードのスパンを示すには、ブロックの先頭と末尾の両方の新しい行に 3 つのバッククォート (```) でラップします。 コードをインラインで示すには、1 つのバッククォート (`) でラップします。

Markdown ウィジェット内で入力されたコードの強調表示により、コードが事前書式設定されたプレーンテキストとしてレンダリングされます。

例:

```
sudo npm install vsoagent-installer -g  
```

結果:

sudo npm install vsoagent-installer -g

例:

```To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm install vsoagent-installer -g`.``` 

結果:

To install the Microsoft Cross Platform Build & Release Agent, run the following command: `$ sudo npm install vsoagent-installer -g`.

Markdown ファイル内では、行の先頭にスペースが 4 つあるテキストが自動的にコード ブロックに変換されます。

コード ブロックの言語識別子を設定して、 highlightjs でサポートされている言語の構文の強調表示を有効にします。

``` language
code
```

その他の例:

``` js
const count = records.length;
```

const count = records.length;

``` csharp
Console.WriteLine("Hello, World!");
```

Console.WriteLine("Hello, World!");

変更の提案

pull request では、コメントを使用して、ファイル内の 1 行以上の置換テキストを提案できます。 ユーザーは、 [変更]を選択することで、推奨される変更を簡単に適用できます。 このアクションにより、変更がプル要求にコミットされます。

Markdown ウィジェット内で入力されたコードの強調表示では、'-' と '+' のプレフィックスが付いた行を含む差分形式でコードがレンダリングされます。

例:

```suggestion
  for i in range(A, B+100, C):
```

詳細については、「 コメントの変更の一部を指定する」を参照してください。

Tables

構造化されたデータをテーブルで整理します。 テーブルは、関数パラメーター、オブジェクト メソッド、および説明マッピングへの明確な名前を持つその他のデータを記述する場合に特に便利です。

• 各テーブル行を独自の行に配置します。
• パイプ文字 |を使用して、表のセルを区切ります。
• テーブル内でパイプ文字を使用するには、円記号 \|でエスケープする必要があります。
• テーブルの最初の 2 行は、列ヘッダーとテーブル内の要素の配置を設定します。
• 列の配置 (左、中央、右) を指定するには、テーブルのヘッダーと本文を分割するときにコロン (:) を使用します。
• 新しい行を開始するには、HTML 区切りタグ (<br/>) を使用します (Wiki 内では動作しますが、他の場所では機能しません)。
• 各行は必ず復帰 (CR) または改行 (LF) で終えてください。
• 作業項目の前後に空白スペースを入力するか、テーブル セル内に記載されている pull request (PR) を入力する必要があります。

例:

| Heading 1 | Heading 2 | Heading 3 |  
|-----------|:-----------:|-----------:|  
| Cell A1 | Cell A2 | Cell A3 |  
| Cell B1 | Cell B2 | Cell B3<br/>second line of text |  

結果 :

リスト

リストを使用して関連アイテムを整理します。 番号付きの順序付きリストを追加したり、箇条書きだけを使用して順序付けされていないリストを追加したりできます。 順序化されたリストは、リスト項目ごとに数字とピリオドで開始します。 順序なしリストは、- で開始します。

各リスト項目は新たな行で開始します。 Markdown ファイルまたはウィジェットで、改行の前に 2 つのスペースを入力して新しい段落を開始するか、2 つの改行を連続して入力して新しい段落を開始します。

順序化されたリスト、または番号付きリスト

用例:

1. First item.
1. Second item.
1. Third item.

結果 :

1. 最初の項目。
2. 2番目の項目。
3. 3番目の項目。

箇条書き

例:

- Item 1
- Item 2
- Item 3

結果 :

• 項目 1
• 項目 2
• 項目 3

入れ子になったリスト

用例:

1. First item.
   - Item 1
   - Item 2
   - Item 3
1. Second item.
   - Nested item 1
      - Further nested item 1
      - Further nested item 2
      - Further nested item 3
   - Nested item 2
   - Nested item 3

結果 :

1. 最初の項目。
   • 項目 1
   • 項目 2
   • 項目 3
2. 2番目の項目。
   • 入れ子になった項目 1
     • さらに入れ子になった項目 1
     • さらに入れ子になった項目 2
     • さらに入れ子になった項目 3
   • 入れ子の項目 2
   • 入れ子の項目 3

リンク

pull request コメントと wiki では、HTTP URL と HTTPS URL はリンクとして自動的に書式設定されます。 作業項目にリンクするには、 # キーと作業項目 ID を入力し、一覧から作業項目を選択します。

作業項目の自動提案を回避するには、 # に円記号 (\) を付けます。 このアクションは、色の 16 進コードに # を使用する場合に便利です。

Markdown ファイルとウィジェットでは、標準の Markdown リンク構文を使用して URL のテキスト ハイパーリンクを設定できます。

[Link Text](Link URL)

同じ Git または Team Foundation バージョン管理 (TFVC) リポジトリ内の別の Markdown ページにリンクする場合、リンク ターゲットには、リポジトリ内の相対パスまたは絶対パスを指定できます。

ウェルカム ページでサポートされているリンク:

• 相対パス: [text to display](target.md)
• Git の絶対パス: [text to display](/folder/target.md)
• TFVC の絶対パス: [text to display]($/project/folder/target.md)
• URL: [text to display](http://address.com)

Markdown ウィジェットのサポートされているリンク:

• URL: [text to display](http://address.com)

Wiki でサポートされているリンク:

• Wiki ページの絶対パス: [text to display](/parent-page/child-page)
• URL: [text to display](http://address.com)

例:

[C# language reference](/dotnet/csharp/language-reference/)

結果:

C# 言語リファレンス

ソース管理の相対リンク

ソース管理ファイルへのリンクは、ウェルカム ページと Markdown ウィジェットのどちらを指定するかによって解釈が異なります。 システムは、相対リンクを次のように解釈します。

• ウェルカム ページ: ウェルカム ページが存在するソース管理リポジトリのルートを基準にして
• Markdown ウィジェット: チーム プロジェクト コレクションの URL ベースに対する相対値

次に例を示します。

アンカー リンク

Markdown ファイル内では、HTML としてレンダリングされると、アンカー ID がすべての見出しに割り当てられます。 アンカー リンクでは、特殊文字もサポートされます。 ID は見出しテキストであり、スペースはダッシュ (-) と小文字で置き換えられます。 アンカー リンクには、次の規則が適用されます。

• ファイル名内の句読点と先頭の空白は無視されます
• 大文字を小文字に変換する
• 文字間のスペースをダッシュに変換する (-)

例:

###Link to a heading in the page

結果:

セクションへのアンカー リンクの構文。...

[Link to a heading in the page](#link-to-a-heading-in-the-page)

別の Markdown ファイル内で見出しを参照することもできます。

[text to display](./target.md#heading-id)  

[text to display](/page-name#section-name)

画像

問題を強調したり、関心を引いたりするために、pull request の次の側面に画像やアニメーション GIF を追加できます。

• Comments
• Markdown ファイル
• Wiki ページ

イメージを追加するには、次の構文を使用します。

![Text](URL)

例:

![Illustration to use for new users](https://azurecomcdn.azureedge.net/cvt-779fa2985e70b1ef1c34d319b505f7b4417add09948df4c5b81db2a9bad966e5/images/page/services/devops/hero-images/index-hero.jpg)

結果:

イメージ ファイルへのパスには、リンク内の別の Markdown ファイルへのパスと同様に、Git または TFVC の相対パスまたは絶対パスを指定できます。

• 相対パス: ![Image alt text](./image.png)
• Git の絶対パス: ![Image alt text](/media/markdown-guidance/image.png)
• TFVC の絶対パス: ![Image alt text]($/project/folder/media/markdown-guidance/image.png)
• 画像のサイズを変更する: IMAGE_URL =WIDTHxHEIGHT

  Note

  必ず等号の前にスペースを入れます。

  • 例: ![Image alt text]($/project/folder/media/markdown-guidance/image.png =500x250)
  • HEIGHT 値を除外することで、WIDTH のみを指定することもできます。 IMAGE_URL =WIDTHx

チェックリストまたはタスク リスト

軽量タスク リストは、PR の説明または Wiki ページの pull request 作成者またはレビュー担当者として、To Do の進行状況を追跡するための優れた方法です。 Markdown ツール バーを選択して開始するか、選択したテキストに書式を適用します。

チェックリストをサポートするには、 [ ] または [x] を使用します。 チェックリストの前に、 -<space> または 1.<space> (数字) を付けます。

例 - 強調表示されたリストにタスク リスト Markdown を適用する

チェック ボックスをオンにして項目を完了としてマークするには、マークダウンを手動で編集し、タスク リストを追加した後で構文を変更する必要があります。

例 - リストをタスク リストとして書式設定する

- [ ] A  
- [ ] B  
- [ ] C  
- [x] A  
- [x] B  
- [x] C  

結果:

Emoji

pull request コメントと Wiki ページでは、絵文字を使用して文字を追加し、要求内のコメントに反応できます。 テキストに一致する絵文字を取得するには、 : 文字で囲まれた気分を入力します。 最も絵文字をサポートしています。

例:

:smile:
:angry:

結果:

絵文字をエスケープするには、'文字を使用してそれらを囲みます。

例:

`:smile:` `:)` `:angry:`

結果:

:smile: :) :angry:

特定の文字またはリテラル文字を入力する Markdown 構文を無視またはエスケープする

Attachments

pull request コメントと Wiki ページでは、ファイルを添付してポイントを説明したり、提案の背後にあるより詳細な理由を示したりできます。 ファイルを添付するには、コメント フィールドまたは Wiki ページ編集エクスペリエンスにドラッグ アンド ドロップします。 コメント ボックスの右上または Wiki ページの書式設定ウィンドウからクリップを選択することもできます。

クリップボードに画像がある場合は、コメント ボックスまたは Wiki ページに貼り付け、コメントまたは Wiki ページに直接レンダリングできます。

イメージ以外のファイルを添付すると、コメント内のファイルへのリンクが作成されます。 リンクに表示されるテキストを変更するには、角かっこの間の説明テキストを更新します。 添付された画像ファイルは、コメントまたは Wiki ページに直接レンダリングされます。 コメントまたは Wiki ページを添付ファイルで保存または更新します。 その後、添付されたイメージを表示し、リンクを選択して添付ファイルをダウンロードできます。

添付ファイルでは、次のファイル形式がサポートされます。

数学表記と文字

Wiki ページと pull request でインライン表記とブロック KaTeX 表記の両方をサポートしています。 サポートされている次の要素を参照してください。

• シンボル
• ギリシャ文字
• 数学演算子
• パワーとインデックス
• 分数と二項
• その他の KaTeX でサポートされる要素

次の例に示すように、数学表記を含めるには、インラインの $ 記号とブロックの $$ で数学的表記を囲みます。

例: ギリシャ文字

$
\alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \kappa, \lambda, \mu, \nu, \omicron, \pi, \rho, \sigma, \tau, \upsilon, \phi, ...
$  


$\Gamma,  \Delta,  \Theta, \Lambda, \Xi, \Pi, \Sigma, \Upsilon, \Phi, \Psi, \Omega$

結果:

例: 代数表記

Area of a circle is $\pi r^2$

And, the area of a triangle is:

$$
A_{triangle}=\frac{1}{2}({b}\cdot{h})
$$

結果:

例: 合計と整数

$$
\sum_{i=1}^{10} t_i
$$


$$
\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x
$$     

結果:

Wiki で Markdown を使用する

次のガイダンスは、Azure DevOps Wiki で使用するための Markdown 構文を示しています。

::: mermaid
<mermaid diagram syntax>
:::

::: mermaid
sequenceDiagram
    Christie->>Josh: Hello Josh, how are you?
    Josh-->>Christie: Great!
    Christie->>Josh: See you later!
:::

::: mermaid
gantt
    title A Gantt chart
    dateFormat YYYY-MM-DD
    excludes 2022-03-16,2022-03-18,2022-03-19
    section Section

    A task          :a1, 2022-03-07, 7d
    Another task    :after a1 , 5d
:::

:::mermaid
graph LR;
    A[Hard edge] -->|Link text| B(Round edge) --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
:::

:::mermaid
classDiagram
    Creature <|-- Superman
    Creature <|-- Vampire
    Creature <|-- Diavolo
    Creature: +int size
    Creature: +int weight
    Creature: +isBenign()
    Creature: +power()
    class Superman{
        +String currentName
        +fly()
        +heal()
    }
    class Vampire{
        -int age
        -canBite()
    }
    class Diavolo{
        +bool is_serving
        +heat()
    }
:::

:::mermaid
stateDiagram-v2
    [*] --> Active
    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
        ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
    }
:::

:::mermaid
journey
    title Home office day
    section Go to work
      Wake up: 1: Me, Dog
      Take shower: 2: Me
      Go downstairs: 3: Me, Dog
      Make coffee: 4: Me
      Have a breakfast: 5: Me, Dog
      Go upstairs: 3: Me, Dog
      Do work: 1: Me, Dog
    section Go home
      Go downstairs: 3: Me, Dog
      Sit down: 5: Me
:::

:::mermaid
pie title Fishermans in countries
    "Norway" : 684
    "Sweeden" : 234
    "Switzerland" : 10
:::

:::mermaid
requirementDiagram
    requirement development_req {
    id: 1
    text: requirements spec.
    risk: medium
    verifymethod: test
    }
    element test_suite {
    type: manual test
    }
    test_suite - verifies -> development_req
:::

# A collapsible section with markdown
<details>
  <summary>Click to expand!</summary>

  ## Heading
  1. A numbered
  2. list
     * With some
     * Sub bullets
</details>

::: video
<iframe width="640" height="360" src="https://www.youtube.com/embed/OtqFyBA6Dbk" allowfullscreen style="border:none"><iframe>
:::

::: query-table <queryid>
:::

Wiki ページから作業項目へのリンク

シャープ記号 (#) を入力し、作業項目 ID を入力します。

Wiki ページで HTML タグを使用する

Wiki ページでは、HTML タグを使用してリッチ コンテンツを作成することもできます。

<p>
 
 [A Markdown link](https://microsoft.com) 
</p>

例 - 埋め込みビデオ

<video src="path of the video file" width=400 controls>
</video>

<video src="https://sec.ch9.ms/ch9/7247/7c8ddc1a-348b-4ba9-ab61-51fded6e7247/vstswiki_high.mp4" width=400 controls>
</video>

例 - リッチ テキスト形式

<p>This text needs to <del>strikethrough</del> <ins>since it is redundant</ins>!</p>
<p><tt>This text is teletype text.</tt></p>
<font color="blue">Colored text</font>
<center>This text is center-aligned.</center>
<p>This text contains <sup>superscript</sup> text.</p>
<p>This text contains <sub>subscript</sub> text.</p>
<p>The project status is <span style="color:green;font-weight:bold">GREEN</span> even though the bug count / developer may be in <span style="color:red;font-weight:bold">red.</span> - Capability of span
<p><small>Disclaimer: Wiki also supports showing small text</small></p>
<p><big>Bigger text</big></p>

結果:

関連記事

• プロジェクト ページまたはウェルカム ページ
• README ファイル
• Markdown ウィジェット
• ダッシュボード
• ウィジェットのカタログ
• Wiki ページの追加と編集