LoginSignup
20
14
@Yarakashi_Kikohshi

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

Last updated at Posted at 2023-03-06

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

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

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

GitHub.com Markdown の総覧

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

また、GitHub.com 内で Markdown を利用できる場所は、以下の 7 つがあります。1 2

  • files（リポジトリ内の Markdown ファイル (e.g. README.md, SECURELY.md )）
  • Tickets (Issues・Pull requests (PRs)・Discussions)
  • Comments（Tickets・Gist 内のコメント）
  • Milestones
  • Releases
  • Wiki 3
  • Gist

これらの記法は、すべての 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 GitHub Flavored Markdown を公開
2010/06/29 Gist の提供開始
2011/03/21 Markdown 絵文字記法の追加
2011/03/23 メンション記法の追加
2011/04/19 Redcarpet の公開
2011/04/19 Fenced code block の追加
2011/04/19 シンタックスハイライトの追加
2012/05/03 セクションリンクの追加
2013/01/09 タスクリスト記法の追加
2013/09/27 Front matter のテーブル表示
2017/03/14 正式な GFM (0.27) の仕様公開
2017/08/15 コードスニペットの表示
2018/11/01 Suggested changes 機能の追加
2021/02/11 Milestones 内の Markdown サポート
2021/09/30 脚注記法の追加
2021/11/16 右横書きのサポート
2021/11/24 画像のテーマ指定方法の追加
2022/01/21 SVG ファイルのサポート
2022/02/03 ラベル記法の追加
2022/02/14 Mermaid のサポート
2022/03/17 GeoJSON、TopoJSON、STL 3D のサポート
2022/05/19 MathJax のサポート
2023/12/14 アラート記法の追加

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

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

GitHub Flavored Markdown

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓+ ✓+ ✓+ ✓+ ✓ ✓

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

GitHub Flavored Markdown (GFM) は CommonMark に 5 つの拡張記法を追加します。
軽微な違いですが、現行の GFM 0.29 は最新の CommonMark 0.30 を参照しておらず、1 つ前の 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 日に公開されました。

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

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

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

  • 0.27：2017/02/20 公開
  • 0.28：2017/08/01 公開
  • 0.29：2019/04/06 公開

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

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

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

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

セクションリンク

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓

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

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

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

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

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

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

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

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

Table of Contents support in Markdown files | GitHub Changelog

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

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

相対リンク

files Tickets Comments Milestones Releases Wiki Gist
✓

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

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

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

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

Markdown 絵文字

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓ ✓

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

例
:smile:, :cat:, :smile_cat:

:smile:, :cat:, :smile_cat:

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

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

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

脚注

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓

PHP Markdown Extra に準じた脚注の記法 ⧉ が提供されています。

Paragraph [^1]

[^1]: This is footnote.

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

Paragraph [^note]

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

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

アラート

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓ ✓

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

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

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

この記法は、Obsidian の Callouts 記法 や Microsoft Learn の Alerts 記法 に類似しています。

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

画像のテーマ指定

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓ ✓

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

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

<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

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

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

削除されるフラグメントによる記法（折りたたみ）
files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓

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

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

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

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

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

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

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

カラーチップの表示

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

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

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

シンタックスハイライト

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓ ✓

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

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

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

GitHub.com Markdown のシンタックスハイライトには、Linguist と多くの外部ツールが利用されています。Linguist が識別できる言語は languages.yml で一覧を見ることが出来ます。

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

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

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

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

数式

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓ ✓

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

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

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

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

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

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

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

ダイアグラム

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓ ✓

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

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

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

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

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

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

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

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

  • Mermaid: .mermaid、.mmd
  • GeoJSON: .geojson
  • TopoJSON: .topojson
  • STL 3D: .stl

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

メンション

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓

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

@user
@organization/team-name

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

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

Ticket の参照

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓+ ✓+ ✓+ ✓+ ✓ ✓

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

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

#123

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

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

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

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

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

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

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

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

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

コミットハッシュの参照

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓

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

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

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

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

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

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

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

Ticket ラベル

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓ ✓ ✓

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

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

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

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

Issues' label

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

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

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

新しいタスクリスト

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

files Tickets Comments Milestones Releases Wiki Gist
Issues 内のみ

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

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

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

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

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

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

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

Suggested changes

files Tickets Comments Milestones Releases Wiki Gist
PRs 内のみ

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

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

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

この記法の大きな特徴は、以下の 3 点にあります。

  • 修正前後が diff のように表示される
    • diff のように修正前のコードを手動で記述しなくても良い
  • 修正提案されたコードをコミットとして取り込むことが出来る（Commit Suggestion・Add suggestion to batch をクリック）

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

  1. PR 内の “Files changed” に移動
  2. 修正提案の必要なファイルに移動
  3. 修正提案の必要な行を選択
  4. ↓ のファイルのような記号をクリックして suggestion コードブロックを挿入
    Botton for suggested changes
  5. コードブロック内に修正提案コードを記述
  6. Add single comment をクリック

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

コードスニペットの表示

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓ ✓

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

Usage of permanent link - GitHub docs

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

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

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

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

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

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

外部リソースの参照

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓

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

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

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

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

Front matter のテーブル表示

files Tickets Comments Milestones Releases Wiki Gist
✓ ✓

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

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

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

余談

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

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

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

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

拡張自動リンクの無効化

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

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

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

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

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

https://www.example.com
@Qiita

オートコンプリート

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

対象 自動補完されるオブジェクト
メンション
(2011/12/07)		 ユーザー ID (@)
絵文字
(2012/10/12)		 Unicode 絵文字 (:)
Ticket
(2012/12/14)		 Ticket 番号 (#)

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

スラッシュコマンド

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

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

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

追記

編集履歴（折りたたみ）
  • 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: アラートの正式リリースに関する追記。

  1. GitHub Pages でも Markdown を利用することが出来ます。しかしながら、ソースは GitHub にホストされているものの、パーサとなる静的サイトジェネレータは Jekyll 等の GitHub.com 外部に頼っています。そのため、GitHub.com Markdown とは異なります。また、Jekyll のデフォルト記法は kramdown です。 ↩

  2. 実は、Ticket のタイトルでは Markdown `code` だけ利用できます ⧉。ただし、` が含まれるような複雑な `` `code` `` は解釈されません。 ↩

  3. Wiki では複数の記法から選択することが出来ますが、今回は Markdown を選択していることを前提とします。（Markdown の他に、AsciiDoc や MediaWiki 等の 9 つの記法が許されている） ↩

20
14
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
20
14