基本的な書き方とフォーマットの構文

見出し

見出しを作成するには、1 つから 6 つの # シンボルを見出しのテキストの前に追加します。 使用する # の個数によって、見出しの階層レベルと書体のサイズが決まります。

# A first-level heading
## A second-level heading
### A third-level heading

2 つ以上の見出しを使用すると、GitHub では自動的に目次が生成されます。この目次には、ファイル ヘッダー内の をクリックするとアクセスできます。 各見出しのタイトルが目次に一覧表示され、タイトルをクリックして選択したセクションに移動できます。

テキストのスタイル設定

コメント フィールドと .md ファイルでは、太字、斜体、取り消し線、下付き、上付きのテキストで強調を示すことができます。

スタイル	構文	キーボード ショートカット	例	出力
太字	** ** または __ __	Command+B (Mac) または Ctrl+B (Windows/Linux)	**This is bold text**	これは太字のテキストです
[斜体]	* * または _ _	Command+I (Mac) または Ctrl+I (Windows/Linux)	_This text is italicized_	このテキストは斜体です
取り消し線	~~ ~~	なし	~~This was mistaken text~~	これは間違ったテキストでした
太字および太字中にある斜体	** ** および _ _	なし	**This text is _extremely_ important**	このテキストは_きわめて_重要です
全体が太字かつ斜体	*** ***	なし	***All this text is important***	このテキストはすべて重要です
Subscript	<sub> </sub>	なし	This is a <sub>subscript</sub> text	これは下付きテキストです
Superscript	<sup> </sup>	なし	This is a <sup>superscript</sup> text	これは上付きテキストです

テキストの引用

> を使用してテキストを引用符で囲みます。

Text that is not a quote

> Text that is a quote

引用テキストはインデントされ、種類の異なる色で表示されます。

コードの引用

単一のバッククォートで文章内のコードやコマンドを引用できます。 バッククォート内のテキストはフォーマットされません。 また、Command + E キー (Mac) または Ctrl + E キー (Windows/Linux) のキーボード ショートカットを押して、Markdown 行内にコード ブロックのバッククォートを挿入することもできます。

Use `git status` to list all new or modified files that haven't yet been committed.

独立したブロック内にコードあるいはテキストをフォーマットするには、3 重のバッククォートを使用します。

Some basic Git commands are:
```
git status
git add
git commit
```

詳しくは、「コードブロックの作成と強調表示」を参照してください。

コード スニペットとテーブルを頻繁に編集する場合は、GitHub のすべてのコメント フィールドで固定幅フォントを有効にするとメリットが得られる可能性があります。 詳しくは、「GitHub 上での執筆とフォーマットについて」を参照してください。

サポートされているカラー モデル

issue、pull request、ディスカッションでは、バックティックを使って文内の色を呼び出すことができます。 バックティック内でサポートされているカラー モデルでは、色の視覚化が表示されます。

The background color is `#ffffff` for light mode and `#000000` for dark mode.

現在サポートされているカラー モデルを次に示します。

Color	構文	例	出力
HEX	`#RRGGBB`	`#0969DA`
RGB	`rgb(R,G,B)`	`rgb(9, 105, 218)`
HSL	`hsl(H,S,L)`	`hsl(212, 92%, 45%)`

リンク

インライン リンクを作成するには、リンク テキストを角かっこ [ ] で囲み、URL をかっこ ( ) で囲みます。 キーボード ショートカットの Command+K を使ってリンクを作成することもできます。 テキストを選んだら、クリップボードから URL を貼り付け、選択範囲からリンクを自動的に作成できます。

テキストを強調表示し、キーボード ショートカット Command+V キーを使うことで、Markdown ハイパーリンクを作成することもできます。 テキストをリンクに置き換える場合は、キーボード ショートカット Command+Shift+V キーを使います。

This site was built using [GitHub Pages](https://pages.github.com/).

セクションリンク

見出しがある任意のセクションに直接リンクできます。 レンダリングされたファイルで自動的に生成されたアンカーを表示するには、セクション見出しにカーソルを合わせて アイコンを表示し、アイコンをクリックしてブラウザーにアンカーを表示します。

編集中のファイル内の見出しのアンカーを決定する必要がある場合は、次の基本的なルールを使用できます。

• 文字は小文字に変換されます。
• スペースはハイフン (-) に置き換えられます。 その他の空白文字または句読点文字は削除されます。
• 先頭と末尾の空白が削除されます。
• マークアップの書式設定は削除され、内容のみが残ります (たとえば、 _italics_ は italics になります)。
• 見出しに対して自動的に生成されるアンカーが同じドキュメント内の以前のアンカーと同じ場合は、ハイフンと自動インクリメント整数を追加することで一意識別子が生成されます。

URI フラグメントの要件の詳細については、「RFC 3986: Uniform Resource Identifier (URI): 一般構文、セクション 3.5」を参照してください。

次のコード ブロックは、レンダリングされたコンテンツの見出しからアンカーを生成するために使用される基本的なルールを示しています。

# Example headings

## Sample Section

## This'll  be a _Helpful_ Section About the Greek Letter Θ!
A heading containing characters not allowed in fragments, UTF-8 characters, two consecutive spaces between the first and second words, and formatting.

## This heading is not unique in the file

TEXT 1

## This heading is not unique in the file

TEXT 2

# Links to the example headings above

Link to the sample section: [Link Text](#sample-section).

Link to the helpful section: [Link Text](#thisll--be-a-helpful-section-about-the-greek-letter-Θ).

Link to the first non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file).

Link to the second non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file-1).

Relative links (相対リンク)

表示されたファイル中で相対リンクと画像パスを定義して、読者がリポジトリ中の他のファイルにアクセスしやすくできます。

相対リンクは、現在のファイルに対する相対的なリンクです。 たとえば、リポジトリのルートに README ファイルがあり、docs/CONTRIBUTING.md に別のファイルがある場合、README の CONTRIBUTING.md への相対リンクは次のようになります。

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHubは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 リンクのパスは、現在のファイルに対する相対パスになります。 / で始まるリンクは、リポジトリ ルートに対する相対パスです。 ./ や ../ のような相対リンクのオペランドをすべて使用できます。

リンク テキストは 1 行に記述する必要があります。 次の例は機能しません。

[Contribution 
guidelines for this project](docs/CONTRIBUTING.md)

相対リンクは、リポジトリをクローンするユーザにも扱いやすいです。 絶対リンクはリポジトリのクローンではうまく働かないかもしれません。リポジトリ内の他のファイルを参照するには、相対リンクを使うことをおすすめします。

カスタム アンカー

標準の HTML アンカー タグ (<a name="unique-anchor-name"></a>) を使用して、ドキュメント内の任意の場所のナビゲーション アンカー ポイントを作成できます。 あいまいな参照を回避するには、name 属性値にプレフィックスを追加するなど、アンカー タグに一意の名前付けスキームを使用します。

アンカーに指定した name 属性の値を使用して、カスタム アンカーにリンクできます。 構文は、見出しに対して自動的に生成されるアンカーにリンクする場合とまったく同じです。

次に例を示します。

# Section Heading

Some body text of this section.

<a name="my-custom-anchor-point"></a>
Some text I want to provide a direct link to, but which doesn't have its own heading.

(… more content…)

[A link to that custom anchor](#my-custom-anchor-point)

画像

! を追加して、代替テキストを [ ] 内にラップすると、画像を表示できます。 代替テキストは、画像内の情報に相当する短いテキストです。 次に、画像のリンクをかっこ () で囲みます。

![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](https://myoctocat.com/assets/images/base-octocat.svg)

GitHub では、問題へのイメージの埋め込み、プル要求、ディスカッション、コメントと .md ファイルがサポートされます。 リポジトリからイメージを表示したり、オンライン イメージにリンクを追加したり、イメージをアップロードしたりできます。 詳細については、「アセットをアップロードする」を参照してください。

相対リンクを使用して画像を表示する例を次に示します。

Context	相対リンク
同じブランチ上の .md ファイル内	/assets/images/electrocat.png
別のブランチ上の .md ファイル内	/../main/assets/images/electrocat.png
リポジトリの問題、プル要求、コメント内	../blob/main/assets/images/electrocat.png?raw=true
別のリポジトリ内の .md ファイル内	/../../../../github/docs/blob/main/assets/images/electrocat.png
別のリポジトリの問題、プル要求、コメント内	../../../github/docs/blob/main/assets/images/electrocat.png?raw=true

詳細については、「相対リンク」を参照してください。

イメージが表示されるテーマの指定

HTML の <picture> 要素と prefers-color-scheme メディア機能を組み合わせて使って、Markdown で画像が表示されるテーマを指定できます。 淡色モードと濃色モードを区別するため、2 つのオプションを使用できます。 これらのオプションを使用して、暗い背景または明るい背景用に最適化された画像を表示できます。 これは、透明な PNG イメージの場合に特に有用です。

たとえば、次のコードでは、明るいテーマの太陽の画像と暗いテーマの月が表示されます。

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

URL に追加されたフラグメント (#gh-dark-mode-only または #gh-light-mode-only) を使うことでテーマに基づいて画像を指定する古い方法は 終了 となり、上記の新しい方法に置き換えられて削除されます。

リスト

1 つまたは複数の行の前に -、*、または + を置くことで、順序なしリストを作成できます。

- George Washington
* John Adams
+ Thomas Jefferson

リストを順序付けするには、各行の前に数字を置きます。

1. James Madison
2. James Monroe
3. John Quincy Adams

入れ子になったリスト

1 つ以上のリストアイテムを他のアイテムの下にインデントすることで、入れ子になったリストを作成できます。

GitHub 上の Web エディター、または Visual Studio Code のようなモノスペース フォントを使用するテキスト エディターを使って、入れ子になったリストを作成するには、リストが揃って見えるように編集できます。 入れ子になったリスト項目の前に、リスト マーカー文字 (- または *) が、その上の項目のテキストの最初の文字の真下にくるまでスペース文字を入力します。

1. First list item
   - First nested list item
     - Second nested list item

モノスペースフォントを使っていない GitHubのコメントエディタで入れ子になったリストを作成するには、入れ子になったリストのすぐ上にあるリストアイテムを見て、そのアイテムの内容の前にある文字数を数えます。 そして、その数だけ空白を入れ子になったリストアイテムの前に入力します。

この例では、入れ子になったリスト アイテムを少なくとも 5 つのスペースでインデントすることで、リスト項目 100. First list item の下に入れ子になったリスト アイテムを追加できます。First list item の前に 5 文字 (100. ) があるためです。

100. First list item
     - First nested list item

同じ方法で、複数レベルの入れ子になったリストを作成できます。 たとえば、最初の入れ子になったリスト アイテムは入れ子になったリスト コンテンツ First nested list item の前に 7 文字 (␣␣␣␣␣-␣) あるため、2 番目の入れ子になったリスト アイテムを 2 文字以上 (9 つ以上のスペース) でインデントする必要があります。

100. First list item
     - First nested list item
       - Second nested list item

その他の例については、「GitHub 用の Markdown 仕様」を参照してください。

タスク リスト

タスク リストを作成するには、リスト アイテムの前に空白、ハイフン、[ ] を付けます。 完了したタスクをマークするには、[x] を使います。

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

タスク リスト アイテムの説明がかっこで始まる場合、そのかっこを \ でエスケープする必要があります。

- [ ] \(Optional) Open a followup issue

詳しくは、「タスクリストについて」を参照してください。

人や Team のメンション

@ とユーザー名またはチーム名を入力することで、人またはチームを GitHub でメンションできます。 これにより通知がトリガーされ、会話に注意が向けられます。 コメントを編集してユーザ名や Team 名をメンションすれば、人々に通知を受信してもらえます。 通知について詳しくは、「通知について」をご覧ください。

@github/support What do you think about these updates?

親チームにメンションすると、その子チームのメンバーも通知を受けることになり、複数のグループの人々とのコミュニケーションがシンプルになります。 詳しくは、「Team について」を参照してください。

@ シンボルを入力すると、プロジェクト上の人々あるいはチームのリストが現れます。 このリストは入力していくにつれて絞り込まれていくので、探している人あるいは Team の名前が見つかり次第、矢印キーを使ってその名前を選択し、Tab キーまたは Enter キーを押して名前の入力を完了できます。 チームについては、@organization/team-name と入力すればそのチームの全メンバーにその会話をサブスクライブしてもらえます。

オートコンプリートの結果は、リポジトリのコラボレータとそのスレッドのその他の参加者に限定されます。

Issue およびプルリクエストの参照

# と入力して、リポジトリ内のサジェストされた Issue とプル要求のリストを表示させることができます。 Issue あるいはプルリクエストの番号あるいはタイトルを入力してリストをフィルタリングし、Tab キーまたは Enter キーを押して、ハイライトされた結果の入力を完了してください。

詳しくは、「自動リンクされた参照と URL」を参照してください。

外部リソースの参照

カスタムの自動リンク参照がリポジトリに設定されているなら、JIRAのIssueやZendeskのチケットのような外部リソースへの参照は、短縮リンクに変換されます。 リポジトリで利用できる自動リンクを知るには、リポジトリの管理権限を持つ人に連絡してください。 詳しくは、「外部リソースを参照する自動リンクの構成」を参照してください。

アセットをアップロードする

ドラッグアンドドロップ、ファイルブラウザから選択、または貼り付けることにより、画像などのアセットをアップロードできます。 アセットをリポジトリ内の Issue、プル要求、コメント、.md ファイルにアップロードできます。

絵文字の使用

:EMOJICODE: とコロンの後に絵文字の名前を入力することで、文章に絵文字を追加できます。

@octocat :+1: This PR looks great - it's ready to merge! :shipit:

: と入力すると、絵文字のサジェストリストが表示されます。 このリストは、入力を進めるにつれて絞り込まれていくので、探している絵文字が見つかり次第、Tab または Enter を押して、ハイライトされているものを入力してください。

使用可能な絵文字とコードの完全な一覧については、「絵文字チート シート」を参照してください。

段落

テキスト行の間に空白行を残すことで、新しいパラグラフを作成できます。

脚注

次の角かっこ構文を使用して、コンテンツに脚注を追加できます。

Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
  This is a second line.

脚注は次のようにレンダリングされます。

警告

アラートは、重要な情報を強調する際に使用できるブロッククォート構文に基づいたMarkdown拡張です。 GitHub では、コンテンツの重要度を示す独特の色とアイコンが表示されます。

アラートは、ユーザーの成功に不可欠な場合にのみ使用し、読者へ過剰な負荷をかけないよう、記事ごとに 1 つまたは 2 つに制限してください。 さらに、アラートを連続して配置しないようにする必要があります。 アラートを他の要素内に入れ子にすることはできません。

アラートを追加するには、アラートの種類を指定する特殊なブロッククォート行を使用し、その後に標準ブロッククォート内のアラート情報を指定します。 5 種類のアラートを利用できます。

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

レンダリングされたアラートを次に示します。

コメントを使用してコンテンツを非表示にする

GitHub に対し、コンテンツを HTML コメント内に配置することで、レンダリングされた Markdown からコンテンツを非表示にすることができます。

<!-- This content will not appear in the rendered Markdown -->

Markdown のフォーマットの無視

GitHub に対し、Markdown のキャラクタの前に \ を使用することで、Markdown のフォーマットを無視 (エスケープ) させることができます。

Let's rename \*our-new-project\* to \*our-old-project\*.

バックスラッシュの詳細については、Daring Fireball の「Markdown Syntax (Markdown 構文)」を参照してください。

Markdown レンダリングの無効化

Markdown ファイルを確認するときは、ファイルの上部にある Code をクリックすると、Markdown レンダリングを無効にして、代わりにファイルのソースを表示することができます。

Markdown レンダリングを無効にすると、ライン リンクなどのソース ビュー機能を使用できます。これは、レンダリングされた Markdown ファイルを表示する場合には使用できません。

参考資料

• GitHub Flavored Markdown の仕様
• GitHub 上での執筆とフォーマットについて
• 高度なフォーマットを使用して作業する
• GitHub 上での書き込みに関するクイックスタート