GitHub.com で利用可能な Markdown 記法を知りたい

<!-- # GitHub.com で利用可能な Markdown 記法を知りたい -->

GitHub.com で利用可能な主な Markdown 記法は GitHub Flavored Markdown (GFM) という仕様に従っています。しかし、GitHub.com では GFM 以外の記法が数多くあります。本記事ではこれらを明らかにします。

:::note info
本記事では、これらの GitHub.com で利用可能な Markdown 記法を “**GitHub.com Markdown**” と呼ぶこととします。

また、Issues・Pull requests (PRs)・Discussions をまとめて “**Tickets**” と呼ぶこととします。Ticket の場合は、ある特定の Issue・Pull request (PR)・Discussion を指すこととします。
:::

<!-- https://github.blog/2012-11-27-html-pipeline-chainable-content-filters/ -->

## GitHub.com Markdown の総覧

https://docs.github.com/ja/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

GitHub.com Markdown には、GitHub Flavored Markdown の他にも以下のような記法・機能があります。

- [GitHub Flavored Markdown (GFM)](#github-flavored-markdown)
- [セクションリンク](#セクションリンク)
- [相対リンク](#相対リンク)
- [Markdown 絵文字](#markdown-絵文字)
- [脚注](#脚注)
- [アラート](#アラート)
- [画像のテーマ指定 (HTML)](#画像のテーマ指定)
- [カラーチップの表示](#カラーチップの表示)
- [シンタックスハイライト](#シンタックスハイライト)
- [数式](#数式)
- [ダイアグラム](#ダイアグラム)
- [メンション](#メンション)
- [Ticket の参照](#ticket-の参照)
- [コミットハッシュの参照](#コミットハッシュの参照)
- [Ticket ラベル](#ticket-ラベル)
- [新しいタスクリスト](#新しいタスクリスト)
- [Suggested changes](#suggested-changes)
- [コードスニペットの表示](#コードスニペットの表示)
- [外部リソースの参照](#外部リソースの参照)
- [Front matter のテーブル表示](#front-matter-のテーブル表示)

また、GitHub.com 内で Markdown を利用できる場所は、以下の 7 つがあります。[^github-pages] [^title-md]

- files（リポジトリ内の Markdown ファイル (e.g. <samp>README.md</samp>, <samp>SECURELY.md</samp> )）
- Tickets (Issues・Pull requests (PRs)・Discussions)
- Comments（Tickets・Gist 内のコメント）
- Milestones
- Releases
- Wiki [^wiki]
- Gist

[^github-pages]: GitHub Pages でも Markdown を利用することが出来ます。しかしながら、ソースは GitHub にホストされているものの、パーサとなる静的サイトジェネレータは [Jekyll][] 等の GitHub.com 外部に頼っています。そのため、GitHub.com Markdown とは異なります。また、Jekyll のデフォルト記法は [kramdown][] です。
[^title-md]: 実は、Ticket のタイトルでは Markdown `` `code` `` だけ利用できます <sup>[⧉][backtick-title]</sup>。ただし、`` ` `` が含まれるような複雑な ``` `` `code` `` ``` は解釈されません。
<!-- [^milestone]: Issues 内では [Milestone][milestone-doc] を作成することが出来ます。この Milestone の Description 内でも Tickets と同様の GitHub.com Markdown が有効になっています。 -->
[^wiki]: [Wiki][wiki-doc] では複数の記法から選択することが出来ますが、今回は Markdown を選択していることを前提とします。（Markdown の他に、AsciiDoc や MediaWiki 等の 9 つの記法が許されている）

[milestone-doc]: https://docs.github.com/ja/issues/using-labels-and-milestones-to-track-work/about-milestones "マイルストーンについて - GitHub Docs"
[wiki-doc]: https://docs.github.com/ja/communities/documenting-your-project-with-wikis/about-wikis "ウィキについて - GitHub Docs"
[backtick-title]: https://github.blog/changelog/2021-04-13-back-tick-code-blocks-are-now-supported-in-titles/ "Back-tick code blocks are now supported in titles | GitHub Changelog"
[jekyll]: https://jekyllrb.com/ "Jekyll • Simple, blog-aware, static sites | Transform your plain text into static websites and blogs"
[kramdown]: https://kramdown.gettalong.org/ "fast, pure-Ruby Markdown-superset converter"

これらの記法は、すべての Markdown 利用可能領域で有効な記法となっているわけではありません。これらの扱いについて、上で示したそれぞれの領域についてどの記法が有効かを表にしておきます。使用可能の場合には “✓” を入れています。

|                        記法 | files |    Tickets    |  Comments  | Milestones | Releases | Wiki | Gist |
| --------------------------: | :---: | :-----------: | :--------: | :--------: | :------: | :--: | :--: |
|    GitHub Flavored Markdown |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|            セクションリンク |  ✓   |               |            |            |          |  ✓  |  ✓  |
|                  相対リンク |  ✓   |               |            |            |          |      |      |
|             Markdown 絵文字 |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|                        脚注 |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |      |  ✓  |
|                    アラート |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|     画像のテーマ指定 (HTML) |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|          カラーチップの表示 |       |      ✓       |     ✓     |     ✓     |          |      |      |
|      シンタックスハイライト |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|                        数式 |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|                ダイアグラム |  ✓   |      ✓       |     ✓     |     ✓     |          |  ✓  |  ✓  |
|                  メンション |       |      ✓       |     ✓     |     ✓     |    ✓    |      |      |
|             Ticket の参照 ∗ |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |  ✓  |  ✓  |
|    コミットハッシュの参照 ∗ |       |      ✓       |     ✓     |     ✓     |    ✓    |      |      |
|             Ticket ラベル ∗ |  ✓   |      ✓       |     ✓     |     ✓     |    ✓    |      |      |
|          新しいタスクリスト |       | Issues 内のみ |            |            |          |      |      |
|         Suggested changes ∗ |       |               | PRs 内のみ |            |          |      |      |
|    コードスニペットの表示 ∗ |       |      ✓       |     ✓     |     ✓     |          |      |      |
|          外部リソースの参照 |       |      ✓       |     ✓     |            |          |      |      |
| Front matter のテーブル表示 |  ✓   |               |            |            |          |      |  ✓  |

特に、“∗” が付されている以下の 5 つの記法は、特定のリポジトリ内部でのみの記法が含まれます。

- Ticket の参照
- コミットハッシュの参照
- Ticket ラベル
- Suggested changes
- コードスニペットの表示

この表を見るとおもしろいことに、Gist 内で利用できない “カラーチップの表示” が Gist のコメント内で利用できることが分かります。

### 記法の変更履歴

GitHub.com Markdown の変更履歴をまとめてみました。

|            公開日            | 履歴                                 |
| :--------------------------: | :----------------------------------- |
|          2008/02/08          | GitHub 設立                          |
|  [2009/04/20][gfm-release]   | GitHub Flavored Markdown を公開      |
|   [2010/06/29][start-gist]   | Gist の提供開始                      |
|          2011/03/21          | Markdown 絵文字記法の追加            |
|          2011/03/23          | メンション記法の追加                 |
| [2011/04/19][redcarpet-blog] | [Redcarpet][] の公開                 |
|          2011/04/19          | Fenced code block の追加             |
|          2011/04/19          | シンタックスハイライトの追加         |
|          2012/05/03          | セクションリンクの追加               |
| [2013/01/09][tasklist-issue] | タスクリスト記法の追加               |
|          2013/09/27          | Front matter のテーブル表示          |
|          2017/03/14          | 正式な GFM (0.27) の仕様公開         |
|          2017/08/15          | コードスニペットの表示               |
|          2018/11/01          | Suggested changes 機能の追加         |
|   [2021/02/11][milestone]    | Milestones 内の Markdown サポート    |
|          2021/09/30          | 脚注記法の追加                       |
|    [2021/11/16][RtoLlang]    | 右横書きのサポート                   |
|          2021/11/24          | 画像のテーマ指定方法の追加           |
|  [2022/01/21][support-svg]   | SVG ファイルのサポート               |
|          2022/02/03          | ラベル記法の追加                     |
|          2022/02/14          | Mermaid のサポート                   |
|          2022/03/17          | GeoJSON、TopoJSON、STL 3D のサポート |
|          2022/05/19          | MathJax のサポート                   |
|          2023/12/14          | アラート記法の追加                   |

[gfm-release]: https://github.blog/2009-04-20-gfm-everywhere/ "GFM Everywhere!"
[redcarpet-blog]: https://github.blog/2011-04-19-rolling-out-the-redcarpet/ "Rolling out the Redcarpet | The GitHub Blog"
[redcarpet]: https://github.com/vmg/redcarpet "The safe Markdown parser, reloaded. - GitHub"
[support-svg]: https://github.blog/changelog/2022-01-21-allow-to-upload-svg-files-to-markdown/ "Allow to upload .svg files to Markdown | GitHub Changelog"
[tasklist-all]: https://github.blog/2014-04-28-task-lists-in-all-markdown-documents/ "Task lists in all markdown documents | The GitHub Blog"
[RtoLlang]: https://github.blog/changelog/2021-11-16-right-to-left-language-support/ "Right-to-left language support | GitHub Changelog"
[milestone]: https://github.blog/changelog/2021-02-11-markdown-support-in-milestones/ "Markdown support in milestones | GitHub Changelog"
[start-gist]: https://github.blog/2010-06-29-starring-gists/ "Starring Gists | The GitHub Blog"
[start-github-pages]: https://github.blog/2008-12-18-github-pages/ "GitHub Pages | The GitHub Blog"
[gist-comments]: https://github.blog/2010-03-30-gist-comments/ "Gist Comments | The GitHub Blog"

これらの記法に関して、記法の追加は段階的に行われます。上の表では、もっとも早くに追加された日を参照しています。

例えば、タスクリストに関しては以下のような段階がありました。

- [2013/01/09][tasklist-issue]: Issues・PRs・Comments への追加
- [2013/06/25][tasklist-gist]: Gist への追加
- [2014/04/28][tasklist-all]: リポジトリ内のすべての Markdown ファイル、[Wiki][tasklist-wiki] への追加

[tasklist-issue]: https://github.blog/2013-01-09-task-lists-in-gfm-issues-pulls-comments/ "Task Lists in GFM: Issues/Pulls, Comments | The GitHub Blog"
[tasklist-gist]: https://github.blog/2013-06-25-task-lists-in-gist/ "Task Lists in Gist | The GitHub Blog"
[tasklist-wiki]: https://github.blog/2014-05-01-wikis-now-with-more-love/ "Wikis: now with more love | The GitHub Blog"
[tasklist-nested]: https://github.blog/2014-05-14-nested-task-lists/ "Nested task lists | The GitHub Blog"

## GitHub Flavored Markdown

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |  ✓\+   |   ✓\+   |   ✓\+    |  ✓\+   |  ✓  |  ✓  |

“✓” の領域では、ソース内の改行を半角スペースとして解釈します。
“✓\+” の領域では、ソース内の改行を強制改行として解釈します。（Soft line breaks を Hard line breaks として解釈する）

https://github.github.com/gfm/

[GitHub Flavored Markdown][gfm-spec] (GFM) は [CommonMark][] に 5 つの拡張記法を追加します。
軽微な違いですが、現行の GFM 0.29 は最新の CommonMark 0.30 を参照しておらず、1 つ前の 0.29 を参照しています。

[gfm-spec]: https://github.github.com/gfm/ "GitHub Flavored Markdown spec"
[commonmark]: https://spec.commonmark.org/0.29/ "CommonMark spec 0.29"

この節では記法を一覧としておき、詳細な記法の紹介は避けておきます。（“†” は GFM による拡張記法）

- ATX スタイル見出し
- Setext スタイル見出し
- パラグラフ
- 斜体・太字
- インラインコード
- 取り消し線 †
- HTML エンティティ参照
- ブロッククォート
- リスト
    - 箇条書きリスト
    - 番号付きリスト
    - タスクリスト †
- コードブロック
    - Indented code blocks
    - Fenced code blocks
- 表 †
- リンク
    - インラインリンク
    - 参照リンク
    - 自動リンク
    - 拡張自動リンク †
- 画像
- テーマ区切り
- HTML（HTML ブロック、raw HTML）
- HTML タグの無効化 †

GFM には “HTML タグの無効化” がありますが、GitHub.com ではセキュリティの問題から、この仕様よりも多くの HTML タグや属性が無効化されています。これは一覧となっていないため注意が必要になります。

この GFM 仕様は 2017 年 3 月 14 日に公開されました。

https://github.blog/2017-03-14-a-formal-spec-for-github-flavored-markdown/

https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/

----------

GFM には、次のような機能も追加されるようになりました。

- <ins>リンク</ins>：
    - リンクへの下線を引くかどうかのアクセシビリティ設定 ([2023/10/18][linkUnderline])
- <ins>タスクリスト</ins>：
    - クリックによるチェック入力 ([2013/01/09][tasklist-issue])
    - リストのネスト対応 ([2014/05/14][tasklist-nested])
    - ドラッグアンドドロップによる並び替え（Tickets、Tickets のコメント内のみ）([2016/05/27][tasklist-sort])
- <ins>コードブロック</ins>：
    - すべてのコードブロックにコピーボタンの追加 ([2021/05/11][copyBottom-blog] <sup>[⧉][natfriedman]</sup>)
- <ins>画像</ins>：
    - GIF 等のアニメーション画像を自動的に再生するかどうかのアクセシビリティ設定 ([2022/05/19][gif-blog])

[linkUnderline]: https://github.blog/changelog/2023-10-18-new-default-underlined-links-for-improved-accessibility/ "New Default: Underlined Links for Improved Accessibility - The GitHub Blog"
[tasklist-sort]: https://github.blog/2016-05-27-drag-and-drop-tasks-in-markdown-task-lists/ "Drag-and-drop tasks in Markdown task lists | The GitHub Blog"
[natfriedman]: https://twitter.com/natfriedman/status/1391862005095485440 "2021/05/11 natfriedman - Twitter"
[copyBottom-blog]: https://github.blog/2021-06-10-whats-new-from-github-changelog-may-2021-recap/#markdown "What’s new from GitHub Changelog? May 2021 Recap - The GitHub Blog"
[gif-blog]: https://github.blog/changelog/2022-05-19-option-to-prevent-animated-images-from-playing-automatically/ "Option to prevent animated images from playing automatically - The GitHub Blog"

----------

CommonMark から派生する GFM のバージョンは、次のような遷移を辿っています。GitHub 公式では過去のバージョンを閲覧することは出来ないため、Wayback Machine によるアーカイブを参照しておきます。

- [0.27][webarchive-gfm-027]：2017/02/20 公開
- [0.28][webarchive-gfm-028]：2017/08/01 公開
- [0.29][webarchive-gfm-029]：2019/04/06 公開

[webarchive-gfm-027]: https://web.archive.org/web/20170317055021/https://github.github.com/gfm/ "GFM 0.27 - Wayback Machine 2017/03/17"
[webarchive-gfm-028]: https://web.archive.org/web/20170809171317/https://github.github.com/gfm/ "GFM 0.28 - Wayback Machine 2017/08/09"
[webarchive-gfm-029]: https://web.archive.org/web/20190408170826/https://github.github.com/gfm/ "GFM 0.29 - Wayback Machine 2019/04/08"

それ以前の [最初期の GFM][gfm-earliest] は、[John Gruber が提唱した Markdown 記法][jg-markdown] に 3 つの記法が加えられたものでした。（現在の CommonMark から派生する GFM には、拡張自動リンクのみが含まれています）

[gfm-earliest]: https://web.archive.org/web/20090421130151/http://github.github.com/github-flavored-markdown/ "Earliest GFM - Wayback Machine 2009/04/21"
[jg-markdown]: https://daringfireball.net/projects/markdown/syntax "Daring Fireball: Markdown Syntax Documentation"

- 拡張自動リンク
- コミットハッシュの参照
- Ticket の `#` 参照

これに加える形で、以下の 3 つの記法が順に追加されたようです。取り消し線と表に関する追加日付は Wayback Machine による [github.github.com/github-flavored-markdown][gfm-spec-waybackmachine] のアーカイブから調べました。

[gfm-spec-waybackmachine]: https://web.archive.org/web/20131201000000*/https://github.github.com/github-flavored-markdown "https://github.github.com/github-flavored-markdown - Wayback Machine"

- タスクリスト ([2013/01/09][tasklist-issue])
- 取り消し線 ([2013/08/06][gfm-strikethrough])
- 表 ([2014/01/22][gfm-table])

[gfm-strikethrough]: https://web.archive.org/web/20130902062140/https://help.github.com/articles/github-flavored-markdown "GFM 06-Aug-13 - Wayback Machine 2013/09/02"
[gfm-table]: https://web.archive.org/web/20140125072047/https://help.github.com/articles/github-flavored-markdown "GFM 22-Jan-2014 - Wayback Machine 2014/01/25"

ただし、タスクリスト記法の公開が 2013/01/09 であるのに対して、参照した記事では少なくとも 2013/02 までタスクリスト記法に関する記述が追加されていませんでした。そのため、正確な日付を保証するものではないことに注意してください。

## セクションリンク

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |         |          |           |         |  ✓  |  ✓  |

見出しを作成した際に、見出しへのアンカー ID が自動的に生成されます。セクションリンクによって見出しを参照することが出来ます。

見出しが `# Heading` の場合、アンカー ID は `heading` として自動的に生成されます。そのため、`[Some Text](#heading)` とすれば `# Heading` 見出しにジャンプするページ内リンクを作成することが出来ます。

このようなアンカー ID への変換則は明示的ではありません。しかしながら、以下のような変換順序を実践的に見ることが出来ます。

1. 大文字から小文字に置き替え
1. 見出しの文字列の内、`[^\p{Word}\- ]` を無視
1. 半角スペースを `-` に置き替え
1. 同一のアンカー ID があった場合は、2 つ目以降の末尾に `-1`、`-2` … を与える

実は、Qiita を含め多くの Markdown パーサにこれに準じた機能がありますが、CommonMark や GFM で仕様として策定されていません。
そのため、パーサによってアンカー ID の作成方法は異なっています。

このセクションリンクは 2012 年 5 月 3 日に公開されました。

https://github.blog/2012-05-03-section-links-in-readmes-and-blob-pages/

----------

Markdown ファイルや Wiki では、このセクションリンクを利用して目次が自動的に作成されます。

リポジトリの Markdown ファイルに見出しが 2 つ以上ある場合、自動的に目次が生成され、上部のドロップダウンから目次を表示させることが出来ます。（[2021/04/13][tocFile-blog] 公開）

![Table of Contents support in Markdown files | GitHub Changelog](https://camo.qiitausercontent.com/3cfdd8b906f8745bc48fa92c46575b598ddadc44/68747470733a2f2f69302e77702e636f6d2f757365722d696d616765732e67697468756275736572636f6e74656e742e636f6d2f373930303038372f3131333832313337302d64663931353438302d393733302d313165622d386165642d6264633530653232313264352e6769663f73736c3d31 "Table of Contents support in Markdown files | GitHub Changelog")

<!-- ![README.md in top directory](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/01b97d67-8bb7-5787-4872-6d271e3b857e.png "目次のドロップダウンが README.md ファイルの左上に表示されている様子") -->
<!-- ![README.md in subdirectory](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/b9da6dd9-b3f4-ebcb-8046-3fcb48187415.png "目次のドロップダウンが README.md ファイルの右上に表示されている様子") -->

[tocFile-blog]:
https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/ "Table of Contents support in Markdown files"

Wiki では、サイドバーへ自動的に目次が生成されます。もしも手動で目次を作成する場合は、<samp>_Sidebar.md</samp> を編集します。（[2021/08/19][tocWiki-blog] 公開）

[tocWiki-blog]: https://github.blog/changelog/2021-08-19-table-of-content-for-wikis/ "Table of contents for Wikis"

Gist にはリポジトリの Markdown ファイルや Wiki のような目次の自動生成機能は提供されていません。

## 相対リンク

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |         |          |           |         |      |      |

リポジトリ内のファイルを参照するリンクを作成することが出来ます。

```markdown
[file.ext](path/to/file.ext)
```

Wiki でも同じように、Wiki 内のファイルを参照するリンクを作成することが出来ますが、拡張子が不要です。（今回、リポジトリ内のファイルを参照しないため除外しています）

相対リンクは 2013 年 1 月 31 日に公開されました。

https://github.blog/2013-01-31-relative-links-in-markup-files/

## Markdown 絵文字

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |   ✓    |  ✓  |  ✓  |

Emoji shortcodes を `:` で囲むことで表現される絵文字です :satisfied:

```markdown: 例
:smile:, :cat:, :smile_cat:
```

:smile:, :cat:, :smile_cat:

Emoji shortcodes の一覧は「[Emoji cheat sheet][ecs] を参照 :pencil:」としています。この一覧は GitHub Emoji API から自動的に生成されています。

[ecs]: https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md "This cheat sheet is automatically generated from GitHub Emoji API and Unicode Full Emoji List."

GitHub.com Markdown で利用できる Markdown 絵文字には、特定の Unicode 絵文字の他、[GitHub.com によるカスタム絵文字][ecs-custom] :octocat: も含まれています :eyes:

[ecs-custom]: https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#github-custom-emoji "§ GitHub custom emoji - This cheat sheet is automatically generated from GitHub Emoji API and Unicode Full Emoji List."

この Markdown 絵文字は 2011 年 3 月 21 日に公開されました :tada:

https://github.blog/2011-03-21-emoji-2/

## 脚注

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |   ✓    |      |  ✓  |

PHP Markdown Extra に準じた脚注の記法 <sup>[⧉][php-footnote]</sup> が提供されています。

[php-footnote]: https://michelf.ca/projects/php-markdown/extra/#footnotes "Footnotes \- PHP Markdown Extra"

```markdown
Paragraph [^1]

[^1]: This is footnote.
```

脚注内には他のブロック要素を含めることも可能です。ブロック要素は `[^label]:` の後行に半角スペース 4 つインデントによってネストできます。

```markdown
Paragraph [^note]

[^note]: This is
list in footnote.
    - first item
    - second item
    - third item
```

この脚注記法は 2021 年 9 月 30 日に公開されました。

https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/

## アラート

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :--------: | :------: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |     ✓     |    ✓    |  ✓  |  ✓  |

注意や警告を促すためのアラート記法が提供されています。

この記法はブロック引用内で `[!alertType]` とします。`alertType` には `Note`・`Warning`・`Important`・`Tip`・`Caution` (case insensitive) のいずれかが入ります。
Markdown としてはブロック引用内ですが、アラート内は `<div>` タグ内にあることに注意してください。

```markdown
> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.
```

![Alert sample](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/ab6014db-2fad-1af5-fe5f-5570d6971cec.png "アラート記法の例")


この記法は、[Obsidian の Callouts 記法][obsidian-callouts] や [Microsoft Learn の Alerts 記法][microsoftlearn-alerts] に類似しています。

[microsoftlearn-alerts]: https://learn.microsoft.com/en-us/contribute/content/markdown-reference#alerts-note-tip-important-caution-warning "Markdown reference for Microsoft Learn - Contributor guide | Microsoft Learn"
[obsidian-callouts]: https://help.obsidian.md/Editing+and+formatting/Callouts "Callouts - Obsidian Help"

この記法の β 版は [2022 年 5 月 19 日][beta-alert-20220519] に公開され、[2023 年 7 月 28 日][beta-alert-20230728]、[2023 年 11 月 14 日][beta-alert-20231114] にアップデートされました。
また、正式版は 2023 年 12 月 14 日にリリースされました。

[beta-alert-20220519]: https://github.com/community/community/discussions/16925 "[Markdown] An option to highlight a “Note” and “Warning” using blockquote (Beta) #16925 - GitHub Discussions"
[beta-alert-20230728]: https://qiita.com/Yarakashi_Kikohshi/items/cf3b72db6f3594a3cc0f "GitHub.com の Markdown でアラート記法が変更された話 - Qiita"
[beta-alert-20231114]: https://qiita.com/Yarakashi_Kikohshi/items/e6802e08921388d8c6e9 "GitHub.com の Markdown でアラート記法が増えた話 - Qiita"

https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/

<!-- 現在、この記法は正式リリースの報告がなされていませんが、[Markdown の構文紹介ページ][github-alerts] では β 版は過去のもののように記述されています。 -->

[github-alerts]: https://docs.github.com/ja/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts "警告 - 基本的な書き方とフォーマットの構文 - GitHub Docs"

## 画像のテーマ指定

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :--------: | :------: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |     ✓     |    ✓    |  ✓  |  ✓  |

これまでのフラグメントを利用した画像テーマの指定は、ブラウザのテーマには従わず、非 GitHub ユーザーはこの恩恵を受けられませんでした。

以下のように、`<picture>` タグと `<source>` タグを利用することで、さまざまな閲覧環境で画像のテーマ指定が可能になりました。

```html
<picture>
    <source media="(prefers-color-scheme: dark)" srcset="link/to/dark/image.png">
    <img src="link/to/light/image.png">
</picture>
```

![Specify theme context for images in Markdown (Beta) | GitHub Changelog](https://camo.qiitausercontent.com/e7a9dca54c1ba26deaf90c57bc4ba804df20c45e/68747470733a2f2f69302e77702e636f6d2f757365722d696d616765732e67697468756275736572636f6e74656e742e636f6d2f333336393430302f3136393237383332322d64393033653332652d663735322d346330662d626637352d3732653561393464306637622e6769663f73736c3d31 "Specify theme context for images in Markdown | GitHub Changelog")

この記法では、ブラウザのテーマ、GitHub.com の概観テーマの双方に従って画像が表示されます。また、Markdown における切り替えと異なり、Markdown 利用可能領域すべてで有効になっています。（おそらく GFM に付随しているためです）

この記法は [2022 年 5 月 19 日][themeContext-blog] に β 版、2022 年 8 月 15 日に正式に公開されました。

[themeContext-blog]: https://github.blog/changelog/2022-05-19-specify-theme-context-for-images-in-markdown-beta/ "Specify theme context for images in Markdown (Beta)"

https://github.blog/changelog/2022-08-15-specify-theme-context-for-images-in-markdown-ga/

----------

<details>
<summary>削除されるフラグメントによる記法（折りたたみ）</summary>

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :--------: | :------: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |            |          |      |  ✓  |

画像を GitHub.com の概観テーマに従って変更することが出来ます。（GitHub.com では “Light” から始まる 4 つのライトテーマと “Dark” から始まる 5 つのダークテーマがある）

画像リンクの後ろに `#` に続く指定子を置くことで、画像を表示するテーマを指定します。

| テーマ |        指定子         |
| :----: | :-------------------: |
| ダーク | `#gh-dark-mode-only`  |
| ライト | `#gh-light-mode-only` |

したがって、次のようにします。これによって、指定子のあるテーマのときのみ表示されるようになります。

```markdown
![Dark theme image](link/to/dark/image.png#gh-dark-mode-only)
![Light theme image](link/to/light/image.png#gh-light-mode-only)
```

![Specify theme context for images in Markdown | GitHub Changelog](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/59bcf856-6e6a-fee0-7b01-5682ed5f875b.png "Specify theme context for images in Markdown | GitHub Changelog")

この記法は 2021 年 11 月 24 日に公開されました。

https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/

</details>

## カラーチップの表示

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|       |   ✓    |    ✓    |    ✓     |         |      |      |

コードスパン内でカラーコードを記述すると、カラーチップを表示することが出来ます。対応している色の指定方法は以下の 4 つがあります。

- HEX: `` `#RRGGBB` ``
- RGB: `` `rgb(R,G,B)` ``
- RGBA: `` `rgba(R,G,B,A)` ``
- HSL: `` `hsl(H,S,L)` ``

Qiita でも、HEX・RGB(A)・HSL(A) を用いてカラーチップを表示させることが出来ます。（e.g. `#0F4C81`）<sup>[⧉][qiita-md-color]</sup>

[qiita-md-color]: https://qiita.com/Qiita/items/c686397e4a0f4f11683d#%E3%82%B3%E3%83%BC%E3%83%89%E3%82%B9%E3%83%91%E3%83%B3%E3%81%AE%E4%B8%AD%E8%BA%AB%E3%81%8Ccss%E3%81%AE-color-%E5%9E%8B "コードスパンの中身が CSS の <color> 型 \- Markdown 記法チートシート"

正確な公開時期を調べることは出来なかったものの、少なくとも 2017 年 4 月には実装されていたようです。<sup>[2017/4/21 のツイート][tomschenkjr]</sup>

[bryanebraun]: https://twitter.com/BryanEBraun/status/916508862450192385 "Bryan Braun - Twitter"
[borekb]: https://twitter.com/borekb/status/859072204050452481 "Borek Bernard - Twitter"
[tomschenkjr]: https://twitter.com/tomschenkjr/status/855237672692051969 "@tomschenkjr@mastodon.world - Twitter"

ちなみに、カラーチップを疑似的に再現したい場合には、[Placehold][] 等を利用すると良いでしょう。

[placehold]: https://placehold.co/ "Placehold | A simple, fast and free image placeholder service"

## シンタックスハイライト

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |   ✓    |  ✓  |  ✓  |

GitHub.com Markdown における Fenced code block にはシンタックスハイライトを与えることが出来ます。多くの Markdown パーサでも利用できますが、シンタックスハイライトの仕様は CommonMark や GFM に記載されていません。（パーサによって指定する言語名が軽微に異なる）

シンタックスハイライトは、Fenced code block を開始する ` ``` ` に続けて言語名等を与えることで有効にすることが出来ます。(case insensitive)

````markdown: 例
```python
print("Hello World")
```
````

GitHub.com Markdown のシンタックスハイライトには、[Linguist][] と多くの外部ツールが利用されています。Linguist が識別できる言語は [languages.yml][linguist-lang] で一覧を見ることが出来ます。
<!-- （リポジトリは [2011/05][linguist-api] 作成） -->

[linguist-api]: https://api.github.com/repos/github/linguist "\"created_at\" at github/linguist - GitHub API"
[linguist]: https://github.com/github/linguist "Language Savant. If your repository's language is being reported incorrectly, send us a pull request! - GitHub"
[linguist-lang]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml "linguist/languages.yml - GitHub"
[diff+lang]: https://github.com/github/linguist/discussions/5758 "Support both language and diff highlighting · github/linguist · Discussion #5758"

language.yml を見れば明らかなように、プログラミング言語やそのエイリアスの他にも、拡張子名や特定のファイル名であっても指定言語としてハイライトを与えることが出来ます。
ただし、後述のダイアグラムと競合する指定言語があることに注意してください。

シンタックスハイライトは、[Redcarpet][] の公開を記念して Fenced code block 記法の追加と同時に 2011/04/19 公開されました。

https://github.blog/2011-04-19-rolling-out-the-redcarpet/

----------

シンタックスハイライトには、プログラミング言語の他に差分を強調表示する `diff` も提供されています。（[2014/12/09][syntaxDiff-blog] 公開）

[syntaxDiff-blog]: https://github.blog/2014-12-09-syntax-highlighted-diffs/

ただし、この `diff` には、他の言語と組み合わせるようなシンタックスハイライト (e.g. `diff_python`) を提供していません。PRs のコメント内に限られますが、Suggested changes が類似記法になります。（[参考][diff+lang]）

## 数式

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |   ✓    |  ✓  |  ✓  |

https://docs.github.com/ja/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

数式を [MathJax][] (v3.2.0) によって表示させることが出来ます。数式の利用箇所は、以下の行内数式とディスプレイ数式の 2 通りがあり、数式を開始・終了するための記法はそれぞれ 2 つずつあります。

[mathjax]: https://www.mathjax.org/ "Beautiful and accessible math in all browsers \- MathJax"

- 行内数式：
    - `$` で囲う（分かち書きを要請する）
    - `` $` ``\~`` `$ `` で囲う
- ディスプレイ数式：
    - `$$` で囲う
    - Fenced code block + `math`
        ````markdown
        ```math
        % ここに数式を書く
        ```
        ````

数式そのものの記法は MathJax に従っています。

MathJax による数式のレンダリングは 2022 年 5 月 19 日に公開されました。

https://github.blog/2022-05-19-math-support-in-markdown/

加えて、Fenced code block + `math` による記法が [2022 年 6 月 28 日][fcbMath-blog]、`` $` ``\~`` `$ `` による記法が [2023 年 5 月 8 日][newDelimiterMath-blog] に公開されました。

[fcbMath-blog]: https://github.blog/changelog/2022-06-28-fenced-block-syntax-for-mathematical-expressions/ "Fenced block syntax for mathematical expressions"
[newDelimiterMath-blog]: https://github.blog/changelog/2023-05-08-new-delimiter-syntax-for-inline-mathematical-expressions/ "New delimiter syntax for inline mathematical expressions"

----------

利便性として、行内数式は `` $` ``\~`` `$ ``、ディスプレイ数式は Fenced code block + `math` を利用すると良いでしょう。これは、`$` や `$$` で囲うような記法は、他の Markdown 記法との競合が発生してしまうためです。
Markdown と MathJax との競合は [この記事][mathjax-md] に紹介されているもの等さまざまあります。また、いくつかの [バグ][github-math-bugs] が報告されています。

[mathjax-md]: https://kmyk.github.io/blog/blog/2020/02/19/portable-mathjax-markdown/ "MathJax と Markdown で可搬性のある数式を書くには - うさぎ小屋"
[github-math-bugs]: https://github.com/nschloe/github-math-bugs "nschloe/markdown-math-acid-test: Showcase GitHub math bugs"

<!--
```markdown
${e}_{ij}$ ${e}_{ij}$

$$
\left\{ e \right\}
$$
```

また、`$` による行内数式は、任意の文字に対して開き側の分かち書きを要請します。`` $` ``\~`` `$ `` はこのような分かち書きを要請しません。（`_` による強調の分かち書きとは仕様が異なります）

次の例を考えた時、`$t$` は LaTeX としてレンダリングされません。これは `時間` と `$t$` の間が分かち書きされていないためです。対して、`$x$`・`` $`v`$ `` は LaTeX としてレンダリングされます。

```markdown
時間$t$、位置 $x$、速度$`v`$。
```
-->

また、MathJax v3 は、パーサ側で必要な拡張を追加できます。GitHub では 35 の拡張の内、19 の拡張のみが有効になっています。
これに関しては次の記事に詳しいです。

https://qiita.com/Yarakashi_Kikohshi/items/8aad73b8f78184bf9b90

## ダイアグラム

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |         |  ✓  |  ✓  |

https://docs.github.com/ja/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams

ダイアグラムが生成されない場合、構文のシンタックスハイライトが加わります。

GitHub では、Fenced code block からダイアグラムを作成できます。このダイアグラムは以下の 4 つに対応しています。Mermaid は UML、GeoJSON・TopoJSON は地図、STL 3D は 3D モデルを描画することが出来ます。

- [Mermaid][] (`mermaid`)
- [GeoJSON][] (`geojson`)
- [TopoJSON][] (`topojson`)
- [STL 3D][stl3d] (`stl`)

[mermaid]: https://mermaid.js.org/#/ "Mermaid \- Diagramming and charting tool"
[geojson]: https://geojson.org/ "GeoJSON is a format for encoding a variety of geographic data structures."
[topojson]: https://github.com/topojson/topojson "An extension of GeoJSON that encodes topology! 🌐 \- GitHub"
[stl3d]: https://ja.wikipedia.org/wiki/Standard_Triangulated_Language#ASCII%E5%BD%A2%E5%BC%8F "\# ASCII 形式 - Standard Triangulated Language \- Wikipedia"

それぞれ、Fenced code block を用いて開始・終了します。例えば、Mermaid は以下のようにします。（指定言語は上のリストの括弧内の文字列）

````markdown
```mermaid
%% ここに Mermaid のダイアグラムを書く
```
````

ダイアグラムの記法そのものは、それぞれの記法に従っています。

これら Mermaid は 2022 年 2 月 14 日、GeoJSON・TopoJSON・SLT 3D は 2022 年 3 月 17 日に公開されました。

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

https://github.blog/changelog/2022-03-17-mermaid-topojson-geojson-and-ascii-stl-diagrams-are-now-supported-in-markdown-and-as-files/

もしもダイアグラムの生成を避けてシンタックスハイライトのみを課したい場合は、指定言語の先頭に `.` を付けてください。(e.g. ` ```.mermaid `)

----------

これらの記法は単独のファイルとしてもレンダリングされます。対応拡張子は以下のようになっています。

- Mermaid: <samp>.mermaid</samp>、<samp>.mmd</samp>
- GeoJSON: <samp>.geojson</samp>
- TopoJSON: <samp>.topojson</samp>
- STL 3D: <samp>.stl</samp>

実際のところ、[2013 年 4 月 9 日][stl-blog] に STL 3D、[2013 年 6 月 13 日][geojson-blog] に GeoJSON の独立ファイルのレンダリングが公開されていました。

[stl-blog]: https://github.blog/2013-04-09-stl-file-viewing/ "STL File Viewing"
[geojson-blog]: https://github.blog/2013-06-13-there-s-a-map-for-that/ "There’s a map for that"

## メンション

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|       |   ✓    |    ✓    |    ✓     |   ✓    |      |      |

`@` にユーザー ID やチーム ID を続けることで、メンションすることが出来ます。
この ID には `[a-zA-Z]`、`[0-9]`、`-` が利用できます。

```markdown
@user
@organization/team-name
```

このメンションを利用すると、メンションしたユーザーやチームに通知が飛ぶようになります。

この記法は 2011 年 3 月 23 日に公開されました。

https://github.blog/2011-03-23-mention-somebody-they-re-notified/

## Ticket の参照

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |  ✓\+   |   ✓\+   |   ✓\+    |  ✓\+   |  ✓  |  ✓  |

“✓\+” の領域では、特定のリポジトリ内部の参照のみの記法が含まれています。

https://docs.github.com/ja/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issue-%E3%81%8A%E3%82%88%E3%81%B3%E3%83%97%E3%83%AB%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88

Ticket の参照で代表的なものは、`#` に Ticket に与えられた番号を続ける記法です。これによって、リポジトリ内にある当該番号の Ticket を参照することが出来ます。

```markdown
#123
```

実はこの他にも、いくつかの Ticket を参照する記法があります。これらは記述する領域によって利用できる記法や表示が異なります。

参照したい Ticket のあるリポジトリ内の場合、以下の 5 つの記法が利用できます。Ticket 内でこれらの記法を利用して参照すると、参照された Ticket 内に参照された旨が表示されるようになります。

|                      参照の種類                      | 書き込み                                         | 実際の表示                                  |
| :--------------------------------------------------: | :----------------------------------------------- | :------------------------------------------ |
|               `#` に続けて Ticket 番号               | `#26`                                            | [#26][jlord-sheetsee-26]                    |
|              `GH-` に続けて Ticket 番号              | `GH-26`                                          | [GH-26][jlord-sheetsee-26]                  |
|                    Ticket の URL                     | `https://github.com/jlord/sheetsee.js/issues/26` | [#26][jlord-sheetsee-26]                    |
|     `Username/Repository#` に続けて Ticket 番号      | `jlord/sheetsee.js#26`                           | [jlord/sheetsee.js#26][jlord-sheetsee-26]   |
| `Organization_name/Repository#` に続けて Ticket 番号 | `github/linguist#4039`                           | [github/linguist#4039][github-linguist4039] |

この記法では、特に `GH-` に続いて数字を書く場合に注意が必要になります。意図せずリンク参照する可能性があります。

参照したい Ticket のあるリポジトリ外部の Tickets・Comments や Markdown ファイル、Gist の場合、以下の 3 つの記法が利用できます。

|                      参照の種類                      | 書き込み                                         | 実際の表示                                  |
| :--------------------------------------------------: | :----------------------------------------------- | :------------------------------------------ |
|                    Ticket の URL                     | `https://github.com/jlord/sheetsee.js/issues/26` | [jlord/sheetsee.js#26][jlord-sheetsee-26]   |
|     `Username/Repository#` に続けて Ticket 番号      | `jlord/sheetsee.js#26`                           | [jlord/sheetsee.js#26][jlord-sheetsee-26]   |
| `Organization_name/Repository#` に続けて Ticket 番号 | `github/linguist#4039`                           | [github/linguist#4039][github-linguist4039] |

[jlord-sheetsee-26]: https://github.com/jlord/sheetsee.js/issues/26
[github-linguist4039]: https://github.com/github/linguist/pull/4039

もしもいずれの領域でも通じる書き方をしたければ、実際の表示が異なってしまうものの、Ticket の URL を書いた方が良いでしょう。

これらの参照が Ticket あるいは Ticket の Comments 内でリスト項目として利用された場合、実際の表示は Ticket のタイトルが表示されるようになります。
また、Ticket 内でタスクリストの項目として利用すると、参照された Ticket の状況を追跡するようになります。

Tickets の `#` 参照は最初期の GFM から存在していました。

<!-- https://github.blog/2012-06-25-auto-updating-comments/ -->

## コミットハッシュの参照

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|       |   ✓    |    ✓    |    ✓     |   ✓    |      |      |

https://docs.github.com/ja/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88-sha

あるコミットを参照したい場合、コミット毎に与えられる 40 文字からなるハッシュ値 (SHA: Secure Hash Algorithm) を書くと、自動的にリンクされます。

参照したいコミットのあるリポジトリ内の場合、以下の 4 つの記法が利用できます。

|      参照の種類       | 書き込み                                                                               | 実際の表示                      |
| :-------------------: | :------------------------------------------------------------------------------------- | :------------------------------ |
|     コミット URL      | `https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e` | [`a5c3785`][jlord-sheetsee-sha] |
|    ハッシュ値のみ     | `a5c3785ed8d6a35868bc169f07e40e889087fd2e`                                             | [`a5c3785`][jlord-sheetsee-sha] |
|      `User@SHA`       | `jlord@a5c3785ed8d6a35868bc169f07e40e889087fd2e`                                       | [`a5c3785`][jlord-sheetsee-sha] |
| `User/Repository@SHA` | `jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e`                           | [`a5c3785`][jlord-sheetsee-sha] |

参照したいコミットのあるリポジトリの外の Tickets・Comments の場合、以下の 2 つの記法が利用できます。

|      参照の種類       | 書き込み                                                                               | 実際の表示                                        |
| :-------------------: | :------------------------------------------------------------------------------------- | :------------------------------------------------ |
|     コミット URL      | `https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e` | [jlord/sheetsee.js@`a5c3785`][jlord-sheetsee-sha] |
| `User/Repository@SHA` | `jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e`                           | [jlord/sheetsee.js@`a5c3785`][jlord-sheetsee-sha] |

[jlord-sheetsee-sha]: https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e

この記法は基本的にリポジトリ内でしか機能しません。Markdown ファイルや Wiki、Gist 内ではリテラルか URL として解釈されます。そのため、どの領域でも通じる書き方をしたければ、コミット URL を書いた方が良いでしょう。

この記法は最初期の GFM から存在していました。

## Ticket ラベル

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |   ✓    |    ✓    |    ✓     |   ✓    |      |      |

Tickets には、それぞれの提起が何に関するのか分かりやすくするために、`bug` や `enhancement` のようなラベルを付けることが出来ます。このラベル URL を Tickets、Comments 内で使用すると、ラベルがレンダリングされます。

URL 自体の構文は次のようになっています。

```markdown
https://github.com/{user}/{repository}/labels/{labelname}
```

例えば、`https://github.com/microsoft/vscode/labels/bug` を microsoft/vscode リポジトリの Issues で利用すると、次のようにレンダリングされます。このラベルのリンク先は、そのリポジトリ Issues 内の `is:open label:bug` となっています。

![Issues' label](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/69aa7edb-04a9-38b0-f9c6-8cc7031b6538.png "Issues' label")

Unicode 絵文字付きのラベルの場合は、URL エンコードされた絵文字を追加します。（ラベルへの絵文字は [2018 年 2 月 22 日][ticket-label] に追加されました）

[ticket-label]: https://github.blog/2018-02-22-label-improvements-emoji-descriptions-and-more/ "Label improvements: emoji, descriptions, and more | The GitHub Blog"

リポジトリの外で利用すると、URL として表示されます。また、ラベルが存在しない場合も同様に URL として表示されます。

この記法は 2022 年 2 月 3 日に追加されました。

https://github.blog/changelog/2022-02-03-reference-labels-in-markdown/

## 新しいタスクリスト

この記法はプライベート β 版です。

| files |    Tickets    | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----------: | :------: | :--------: | :------: | :--: | :--: |
|       | Issues 内のみ |          |            |          |      |      |

https://docs.github.com/ja/issues/managing-your-tasks-with-tasklists/creating-a-tasklist

https://github.com/community/community/discussions/39106

タスクリストは GFM によって仕様が決められています。このタスクリストを Issues 内で利用すると、タスクがどの程度完了しているか把握するようになります。また、タスクとして他の Issue をリスト化すると、これらの Issue を監視します。（GFM のタスクリストは “task lists” と表現されています）

新しいタスクリスト (tasklists) では、Fenced code block を利用してタスクリストを表現します。

````markdown
```[tasklist]
## Tasks
- [ ] #1
- [ ] https://github.com/jlord/sheetsee.js/issues/26
- [ ] task
- [x] done task
```
````

これによって、タスクリストの関係性を明らかにしつつ、まとまりのあるタスクを複数持っていることを表現できるようになりました。（[参考][track-tasklists]）
同時に、この新しいタスクリストでは、[Projects][github-project] の “Tracks” や “Tracked by” の対象になります。（それまでの GFM のタスクリストでは UI 上の監視だけで Projects との連携はありませんでした）

[track-tasklists]: https://docs.github.com/ja/issues/managing-your-tasks-with-tasklists/about-tasklists "タスクリストについて - GitHub Docs"
[github-project]: https://docs.github.com/ja/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects "Projects について - GitHub Docs"

現在プライベート β 版のため、すべてのアカウントでの利用は出来ません。もしも試験的に利用したい場合は [プライベート β 版に申し込む][github-beta] か、利用可能になっているアカウント (e.g. [microsoft/vscode][microsoft-vscode]) の Issues 内で利用できます。

[github-beta]: https://docs.github.com/ja/get-started/using-github/exploring-early-access-releases-with-feature-preview "機能プレビューで早期アクセスリリースに触れる - GitHub docs"
[microsoft-vscode]: https://github.com/microsoft/vscode/issues "Issues - microsoft/vscode"

この記法は 2022 年 11 月 15 日に公開されました。

Projects と新しいタスクリストについての詳細は、「[プロジェクトとタスクリストの使用][project-tasklists]」や「[追跡と追跡対象フィールドについて][track-tracked]」を参照してください。

[project-tasklists]: https://docs.github.com/ja/issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists "プロジェクトとタスクリストの使用 - GitHub Docs"
[track-tracked]: https://docs.github.com/ja/issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields "追跡と追跡対象フィールドについて - GitHub Docs"

## Suggested changes

| files | Tickets |  Comments  | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :--------: | :-------: | :-----: | :--: | :--: |
|       |         | PRs 内のみ |           |         |      |      |

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request

Pull request されたコードをレビューする際に、修正すべき箇所があった場合、Fenced code block + `diff` を使って差分を表現しながら修正を促すことがあります。これに PR 側が修正提案を受け入れる場合、PR と同程度の作業が必要でした。これをより簡便にするために、修正の必要な行を選択・抜き出し、特定部分のコードを修正提案できる記法・機能があります。

この修正提案コードの記述は、Fenced code block + `suggestion` で表現されます。

````markdown
```suggestion
This is only suggested change code!!
```
````

この記法の大きな特徴は、以下の 3 点にあります。
- 修正前後が `diff` のように表示される
    - `diff` のように修正前のコードを手動で記述しなくても良い
- 修正提案されたコードをコミットとして取り込むことが出来る（`Commit Suggestion`・`Add suggestion to batch` をクリック）

ちなみに、具体的な修正提案の方法は次のように行います。

1. PR 内の “Files changed” に移動
1. 修正提案の必要なファイルに移動
1. 修正提案の必要な行を選択
1. ↓ のファイルのような記号をクリックして `suggestion` コードブロックを挿入 <br><img src = "https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/0053ee03-a932-60d7-217d-2f559b38b119.png" width = "7%" alt = "Botton for suggested changes">
1. コードブロック内に修正提案コードを記述
1. `Add single comment` をクリック

この機能は 2018 年 11 月 1 日に追加されました。

https://github.blog/2018-11-01-suggested-changes-update/

## コードスニペットの表示

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|       |   ✓    |    ✓    |    ✓     |         |      |      |

https://docs.github.com/ja/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet

リポジトリ内の特定コミットのファイルを URL からコードスニペットとして表示することが出来ます。このコードスニペットは複数行を選択することも出来ます。

![Usage of permanent link - GitHub docs](https://camo.qiitausercontent.com/2bdf7df30f0e9cbe1bef0d9239fa0bccee658cad/68747470733a2f2f6769746875622e626c6f672f77702d636f6e74656e742f75706c6f6164732f323031372f30382f32393132393733332d63363832646134342d376366352d313165372d386337332d3765616561323734633561652e6769663f726573697a653d31333630253243363030 "Usage of permanent link - GitHub docs")

<!-- https://github.blog/wp-content/uploads/2017/08/29129733-c682da44-7cf5-11e7-8c73-7eaea274c5ae.gif?resize=1360%2C600  -->

1. 選択したいリポジトリ内ファイルに移動する
1. コードスニペットとして表示したい行をクリックする
    - `Shift` を押しながら必要な行の末をクリックすると複数行を選択できる
1. 行番号左の `⋯` を選択し、`Copy permalink` をクリック
1. コピーされた URL を貼り付ける

URL 自体の構文は次のようになっています。

```markdown
https://github.com/{user}/{repository}/blob/{SHA}/{path/to/file}#{line-numbers}
```

ただし、このパーマリンクはそのリポジトリ内でのみコードスニペットとして表示され、それ以外のリポジトリでは URL リンクとして表示されます。

この機能は 2017 年 8 月 15 日に追加されました。

https://github.blog/2017-08-15-introducing-embedded-code-snippets/

Markdown ファイルでは、クエリ `?plain=1` を与えることで、他の言語と同じようにコードスニペットを表示できます。この記法は [2021 年 6 月 30 日][parameterMd-blog] に公開されました。

[parameterMd-blog]: https://github.blog/changelog/2021-06-30-parameter-to-disable-markdown-rendering/ "Parameter to disable markdown rendering"

## 外部リソースの参照

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :--------: | :------: | :--: | :--: |
|       |   ✓    |    ✓    |            |          |      |      |

https://docs.github.com/ja/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources

JIRA の Issue や Zendesk のチケットなど外部リソースへの自動リンクを追加して、ワークフローをスムーズにすることが出来ます。

これは Ticket の参照にあった `GH-` のように、外部リソースのチケットなどを “任意の文字列-数字” で表現できるようになります。リポジトリ毎に Settings から構成する必要があります。

例えば、`https://jira.example.com/issue?query=123` のような JIRA の参照を `JIRA-123` に変更することが出来ます。

これは 2019 年 10 月 14 日に公開されました。

https://github.blog/2019-10-14-introducing-autolink-references/

## Front matter のテーブル表示

| files | Tickets | Comments | Milestones | Releases | Wiki | Gist |
| :---: | :-----: | :------: | :-------: | :-----: | :--: | :--: |
|  ✓   |         |          |           |         |      |  ✓  |

Markdown ファイルには、Front matter と呼ばれる YAML 形式で書かれたメタデータを付す場合があります。

GitHub では、これらのメタデータを Markdown 内で利用することはありませんが、表としてレンダリングします。
表としてレンダリングされない領域では、テーマ区切りと Setext スタイル見出しとして無理やり解釈されます。

この機能は 2013 年 9 月 27 日に公開されました。

https://github.blog/2013-09-27-viewing-yaml-metadata-in-your-documents/

# 余談

GitHub.com Markdown は GFM 以外にも複数の記法が存在します。
逆に言えば、GFM と言ったときに Markdown 絵文字や脚注等は含まれていません。

数式やダイアグラムは外部のツールを導入しているものの、それ以外は GitHub.com 内部の記法となっています。これらは GFM に仕様として策定されないのでしょうか。
特に、セクションリンク、Markdown 絵文字、脚注について策定しておいても良いように思います。

特定の URL は、GitHub.com にとって意味のある形で表示が変わるものが多いです。ある程度覚えておくと、より有意義に利用できるでしょう。

ところ変わって、[GitLab][] で利用可能な [GitLab Flavored Markdown (GLFM)][gitlab-flavored-markdown] でもさまざまな記法が決められています。（GitHub.com にない記法も数多くある）

[gitlab]: https://about.gitlab.com/ "The DevSecOps Platform | GitLab"
[gitlab-flavored-markdown]: https://docs.gitlab.com/ee/user/markdown.html "GitLab Flavored Markdown (GLFM) | GitLab"


## 拡張自動リンクの無効化

GitHub.com Markdown では、複数の拡張された自動リンク記法があります。これらは基本的に `\` によって無効化することが出来ません。

これを無効化するには、記法の途中で意味の無い HTML タグを挿入すると良いでしょう。この方法は公式に記載されていませんが、実践的に有効な方法となっています。

```markdown
https:/<hoge>/www.example.com
#<foo>1
@<bar>user
```

これは、Qiita のメンションでも利用できます。

```markdown
https:/<hoge>/www.example.com
@<foo>Qiita
```

https:/<hoge>/www.example.com
@<foo>Qiita

## オートコンプリート

GitHub.com では、以下の 3 つの項目に対して自動補完がなされます。括弧内の文字を入力すると、自動補完が開始されます。

|                    対象                     | 自動補完されるオブジェクト |
| :-----------------------------------------: | :------------------------- |
| メンション <br>([2011/12/07][mention-auto]) | ユーザー ID (`@`)          |
|    絵文字 <br>([2012/10/12][emoji-auto])    | Unicode 絵文字 (`:`)       |
|    Ticket <br>([2012/12/14][issue-auto])    | Ticket 番号 (`#`)          |

[emoji-auto]: https://github.blog/2012-10-12-emoji-autocomplete/ "Emoji autocomplete - The GitHub Blog"
[issue-auto]: https://github.blog/2012-12-14-issue-autocompletion/ "Issue autocompletion - The GitHub Blog"
[mention-auto]: https://github.blog/2011-12-07-mention-autocompletion/ "@mention autocompletion - The GitHub Blog"

絵文字の自動補完に関して、[2020/07/17][emoji-skin] には、自動補完される [絵文字スキントーン][emojiSkinTone] を指定できるようになりました。このスキントーンは [Appearance][emoji-appear] から指定できます。
また、[2021/02/11][emoji-add] には自動補完が多くの場所で利用できるようになりました。

<!-- [emojiSkinTone]: https://www.w3schools.com/charsets/ref_emoji_skin_tones.asp "HTML Emoji Skin Tones" -->
[emojiSkinTone]: https://unicode.org/emoji/charts/full-emoji-modifiers.html "Full Emoji Modifier Sequences - Unicode"
[emoji-add]: https://github.blog/changelog/2021-02-11-additional-emoji-support/ "Additional emoji support - The GitHub Blog"
[emoji-skin]: https://github.blog/changelog/2020-07-17-customizable-skin-tones-in-emoji-autocomplete/ "Customizable skin tones in emoji autocomplete - The GitHub Blog"
[emoji-appear]: https://github.com/settings/appearance#emoji-heading "Appearance"

## スラッシュコマンド

https://docs.github.com/en/issues/tracking-your-work-with-issues/about-slash-commands

Tickets 内で、以下のようなスラッシュコマンドを利用できます。これによって、より平易に Markdown を利用できるようになります。

|     コマンド     | 説明                                                                                        |
| :--------------: | :------------------------------------------------------------------------------------------ |
|     `/code`      | Fenced code block を挿入する。言語の選択が可能。                                            |
|    `/details`    | 折りたたみを挿入する。                                                                      |
|     `/table`     | Markdown 表の挿入。列数と行数の選択が可能。                                                 |
|   `/template`    | リポジトリ内のテンプレートを表示・選択・挿入する。<br>（Issue・PR のみ）                    |
| `/saved-replies` | 保存されている [返信テンプレート][reply-temp] を挿入する。<br>`%cursor%` にカーソルを置く。 |
|   `/tasklist`    | プライベート β 版のタスクリストを挿入する。                                                 |

[reply-temp]: https://docs.github.com/ja/get-started/writing-on-github/working-with-saved-replies "返信テンプレートを使って作業する - GitHub docs"

このコマンドは 2023 年 3 月 15 日に公開されました。

https://github.blog/changelog/2023-03-15-introducing-the-github-markdown-helpers-public-beta/

# 追記

<details>
<summary>編集履歴（折りたたみ）</summary>

- 2023/03/18: 各記法の公開時期の追記、各記法が利用可能な領域の追加、複数の記法を追加しました。
- 2023/03/18: 2 つの記法を追加しました。
- 2023/04/04: 2 つの記法を追加しました。各記法の節に記法領域を示す表を付しました。その他軽微修正。
- 2023/04/29: 軽微修正。
- 2023/05/09: 新しい数式の区切り文字について追加。
- 2023/05/19: 軽微修正。
- 2023/06/01: GFM のアーカイブから、いくつかの記法の出自について追記。数式記法について追記。軽微修正。
- 2023/06/11: 強制改行について追記。軽微修正。
- 2023/08/07: 複数の画像を追加。数式に関する追記。軽微修正。
- 2023/09/12: アラートに関する記法を追加。軽微修正。
- 2023/11/07: Milestones と Releases に関して追記。相対リンクを追加。オートコンプリートを追加。
- 2023/11/28: フラグメントによる画像のテーマ指定が削除されるため追記。アラートのアップデートに関する追記。軽微修正。
- 2023/12/16: アラートの正式リリースに関する追記。

</details>