GitHub 上での書き込みに関するクイックスタート

GitHub プロファイルの README を作成し、高度な書式設定機能について学習します。

この記事の内容

はじめに

Markdown は、プレーンテキストを書式設定するための読みやすく書きやすい言語です。 Markdown 構文を他の HTML タグと併用して、リポジトリの README および、プル リクエストや issues のコメントにおける、GitHub の記述の形式を設定できます。 このガイドでは、GitHub プロファイルの README を作成または編集することで、いくつかの高度な書式設定機能について学習します。

Markdown を初めて使う場合は、「基本的な書き方とフォーマットの構文」または「Markdown を使用したコミュニケーション」GitHub Skills コースから始めるとよいでしょう。

既にプロファイルの README がある場合は、既存の README にいくつかの機能を追加するか、about-me.md のような名前の Markdown ファイルを使用して gist を作成することで、このガイドに従うことができます。 詳しくは、「Gist の作成」を参照してください。

プロファイルの README を作成または編集する

プロフィール README を使用すると、GitHub で自分に関する情報をコミュニティと共有できます。 README はプロファイル ページの上部に表示されます。

プロファイルの README がまだない場合は、追加できます。

  1. GitHub ユーザー名と同じ名前のリポジトリを作成し、そのリポジトリを README.md ファイルで初期化します。 詳しくは、「プロフィールの README を管理する」を参照してください。
  2. README.md ファイルを編集し、ファイルの作成時に自動的に追加される (### Hi there で始まる) テンプレート テキストを削除します。

既にプロファイルの README がある場合は、プロファイル ページからそれを編集できます。

  1. 任意の GitHub Enterprise Server ページ上の右上隅にある自分のプロフィール写真をクリックしてから、 [自分のプロフィール] をクリックします。

  2. プロファイルの README の横にある をクリックします。

    @octocat のプロファイルの README のスクリーンショット。 鉛筆アイコンが濃いオレンジで囲まれています。

訪問者に合わせた画像を追加する

GitHub でのコミュニケーションに画像を含めることができます。 ここでは、プロファイルの README の上部に、バナーなど応答性の高い画像を追加します。

prefers-color-scheme メディア機能で HTML の <picture> 要素を使用すると、訪問者がライト モードとダーク モードのどちらを使用しているかに応じて変化する画像を追加できます。 詳しくは、「テーマ設定を管理する」を参照してください。

  1. 次のマークアップをコピーして README.md ファイルに貼り付けます。

    HTML
    <picture>
 <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE">
 <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE">
 <img alt="YOUR-ALT-TEXT" src="YOUR-DEFAULT-IMAGE">
</picture>

  2. マークアップ内のプレースホルダーを、選んだ画像の URL に置き換えます。 または、最初にこの機能を試すには、次に示す例から URL をコピーできます。

    • YOUR-DARKMODE-IMAGE は、ダーク モードを使用している訪問者に対して表示する画像の URL に置き換えます。
    • YOUR-LIGHTMODE-IMAGE は、ライト モードを使用している訪問者に対して表示する画像の URL に置き換えます。
    • YOUR-DEFAULT-IMAGE は、他の画像のいずれも一致しない場合に表示する画像の URL に置き換えます (たとえば、訪問者が使用しているブラウザーで prefers-color-scheme 機能がサポートされていない場合など)。

  3. スクリーン リーダーを使用している訪問者が画像にアクセスできるようにするには、YOUR-ALT-TEXT を画像の説明に置き換えます。

  4. 画像が正しくレンダリングされたことを確認するには、 [プレビュー] タブをクリックします。

Markdown でのイメージの使用について詳しくは、「基本的な書き方とフォーマットの構文」をご覧ください。

応答性の高い画像の例

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

画像の外観

GitHub コメントの [プレビュー] タブのスクリーンショット。ライト モードになっています。 ボックスには笑顔の太陽が描かれています。

テーブルを追加する

Markdown のテーブルを使用して情報を整理できます。 ここでは、テーブルを使用して、よく使っているプログラミング言語やフレームワーク、学習に時間を費やしていること、好きな趣味など、何かをランク付けして自己紹介します。 テーブル列に数値が含まれている場合は、ヘッダー行の下で構文 --: を使用して列を右揃えにすると便利です。

  1. [ファイルの編集] タブに戻ります。

  2. 自己紹介するには、次のように、</picture> タグの 2 行下で、## About me ヘッダーと自分に関する短い段落を追加します。

    ## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

  3. この段落の 2 行下に、次のマークアップをコピーして貼り付けてテーブルを挿入します。

    Markdown
    | Rank | THING-TO-RANK |
|-----:|---------------|
|     1|               |
|     2|               |
|     3|               |

  4. 右側の列で、THING-TO-RANK を "Languages"、"Hobbies" などに置き換え、列に項目の一覧を入力します。

  5. テーブルが正しくレンダリングされたことを確認するには、 [プレビュー] タブをクリックします。

詳しくは、「情報を表に編成する」を参照してください。

テーブルの例

## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

テーブルの外観

GitHub コメントの [プレビュー] タブのスクリーンショット。 [About me] の見出しの下には、ランク付けされた言語の一覧を含むレンダリングされたテーブルがあります。

折りたたみセクションを追加する

コンテンツを整理しておくために、<details> タグを使用して、展開可能な折りたたまれたセクションを作成できます。

  1. 作成したテーブルの折りたたまれたセクションを作成するには、次の例のように、テーブルを <details> タグ内にラップします。

    HTML
    <details>
<summary>My top THINGS-TO-RANK</summary>

YOUR TABLE

</details>

  2. <summary> タグの間で、THINGS-TO-RANK を、テーブルでランク付けしたものに置き換えます。

  3. 必要に応じて、セクションを既定で開いているように表示するには、open 属性を <details> タグに追加します。

    <details open>

  4. 折りたたまれたセクションが正しくレンダリングされたことを確認するには、 [プレビュー] タブをクリックします。

折りたたまれたセクションの例

<details>
<summary>My top languages</summary>

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

</details>

折りたたまれたセクションの外観

コメントの [プレビュー] タブのスクリーンショット。 "Top languages" という単語の左側には、セクションを展開できることを示す矢印があります。

引用文を追加する

Markdown には、コンテンツを書式設定するための他の多くのオプションがあります。 ここでは、ページとブロック引用を分割する横罫線を追加し、お気に入りの引用文を書式設定します。

  1. ファイル下部の </details> タグの 2 行下に、3 個以上のダッシュを入力して横罫線を追加します。

    ---

  2. --- 行の下に、次のようなマークアップを入力して引用文を追加します。

    > QUOTE

    QUOTE を任意の名前に置き換えます。 または、次の例から引用文をコピーします。

  3. すべてが正しくレンダリングされたことを確認するには、 [プレビュー] タブをクリックします。

引用符の例

---
> If we pull together and commit ourselves, then we can push through anything.

— Mona the Octocat

引用符の外観

GitHub コメントの [プレビュー] タブのスクリーンショット。 引用符が太い横罫線の下にインデントされています。

コメントを追加する

HTML コメント構文を使用して、出力で非表示になるコメントを追加できます。 ここでは、後で README の更新を忘れないようにするためのコメントを追加します。

  1. ## About me ヘッダーの 2 行下に、次のマークアップを使用してコメントを挿入します。

    <!-- COMMENT -->

    COMMENT を、後で何かをする (たとえば、テーブルに項目を追加する) ことを忘れないようにするための "To Do" 項目に置き換えます。

  2. コメントが出力で非表示になっていることを確認するには、 [プレビュー] タブをクリックします。

コメントの例

## About me

<!-- TO DO: add more details about me later -->

作業を保存する

変更に問題がなければ、[変更のコミット] をクリックしてプロファイルの README を保存します。

main ブランチに直接コミットすると、プロファイルのすべての訪問者に変更が表示されます。 作業内容を保存するが、プロファイルに表示する準備ができていない場合は、 [このコミット用に新しいブランチを作成して pull request を開始する] を選ぶことができます。

次のステップ