現在、GitHub AE は限定的リリースです。

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

この記事の内容

自分に関する gist を作成して、高度な書式設定機能について学習します。

はじめに

Markdown は、プレーンテキストを書式設定するための読みやすく書きやすい言語です。 Markdown 構文を追加の HTML タグと共に使用して、GitHub のリポジトリの README や、pull request や issue に関するコメントなどの場所での書き込みを書式設定できます。 このガイドでは、gist を作成することで、いくつかの高度な書式設定機能について説明します。

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

Gist の作成

gist を使用すると、ご自分のエンタープライズ 上でコード スニペットやその他の情報を保存または他のユーザーと共有できます。 gist で書式設定機能を使用するには、拡張子 .md の付いた gist ファイルを追加します。

  1. gist ホーム ページ http(s)://gist.[hostname]に移動します。
  2. 必要に応じて、gist の説明 (「About me」など) を入力します。
  3. [拡張子を含むファイル名] フィールドに「about-me.md」と入力します。

詳しくは、「Gist の作成」を参照してください。

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

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

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

  1. 次のマークアップをコピーし、about-me.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 コメント構文を使用して、出力で非表示になるコメントを追加できます。 ここでは、後で gist を更新するのを忘れないようにするためのコメントを追加します。

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

    <!-- COMMENT -->

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

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

コメントの例

## About me

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

作業を保存する

変更に問題がなければ、gist を保存します。

  • gist を検索エンジンから隠したまま、URL を共有している相手には表示されるようにするには、 [シークレット gist の作成] をクリックします。
  • ご自分のエンタープライズ 上のあらゆるユーザーに gist を表示してよければ、 [内部 gist の作成] をクリックします

次の手順