GitHub Docs での Markdown と Liquid の使用

Markdown と Liquid を使って、さまざまなバージョンの GitHub Docs に対してコンテンツの書式設定、再利用可能なコンテンツの作成、コンテンツの書き込みを行うことができます。

この記事の内容

GitHub Docs での Markdown と Liquid の使用について

GitHub Docs は Markdown を使って記述されます。これは、プレーンテキストを書式設定するための人間にとってわかりやすい構文です。 GitHub Flavored Markdown という名前の Markdown のバリアントが使われ、CommonMark に準拠するようにしています。 詳しくは、「GitHub 上での執筆とフォーマットについて」を参照してください。

Liquid 構文を使って機能が拡張され、アクセスしやすいテーブルや、保守しやすいリンク、バージョン管理、変数、および大量の再利用可能なコンテンツが提供されます。 Liquid について詳しくは、Liquid のドキュメントを参照してください。

このサイトのコンテンツでは、/src/content-render を利用した Markdown レンダリングが使われています。これは remark Markdown プロセッサに基づいて構築されています。

リスト

リスト アイテムについて、最初の段落の後の追加コンテンツに関する一般的なルールは次のとおりです。

  • 画像とその後の段落は、それぞれ独立した行に配置し、空白行で区切る必要があります。
  • リスト アイテム内の後続のすべての行は、リスト マーカー後の最初のテキストに合わせる必要があります。

リストの使用例

次の例は、複数の段落やオブジェクトを含むリスト アイテムを配置する正しい方法を示しています。

1. Under your repository name, click **Actions**.

   ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png)

   This is another paragraph in the list.

1. This is the next item.

このコンテンツは、最初のリスト アイテム以下のコンテンツが正しく配置された状態で GitHub Docs サイトに表示されます。

GitHub Docs でレンダリングされたリストの例

  1. リポジトリ名の下にある [アクション] をクリックします。

    "github/docs" リポジトリのタブのスクリーンショット。 [アクション] タブがオレンジ色の枠線で強調表示されています。

    リスト内の別の段落です。

  2. 次のアイテムです。

警告

アラートは、ユーザーが知っておく必要がある重要な情報が強調表示されます。 4つの異なるタイプのアラートに標準的な書式と色を使用しています：[注意]、[ヒント]、[警告]、[注意]です。

アラートを使用するタイミングと Markdown でコールアウトを書式設定する方法については、「スタイル ガイド」を参照してください。

アラートの例

> [!NOTE] Keep this in mind.

> [!NOTE]
> Generally alerts should be short.
>
> But occasionally may require more than one paragraph

GitHub Docs でレンダリングされたアラートの例

Note

通常、アラートは短くする必要があります。

しかし、場合によっては、複数の段落が必要になる場合があります

コード サンプルの構文の強調表示

コマンド ライン命令やコード サンプルで構文の強調表示をレンダリングするには、3 つのバッククォートの後にサンプルの言語を記述します。 サポートされているすべての言語の一覧については、code-languages.yml を参照してください。

コードの構文の強調表示の使用例

```bash
git init YOUR-REPOSITORY
```

コード サンプルの構文内では、すべて大文字のテキストを使って、プレースホルダーのテキストやユーザーごとに異なるコンテンツ (ユーザー名やリポジトリ名など) を示します。 既定では、コード ブロックでは 3 つのバッククォート内のコンテンツはエスケープされます。 コンテンツを解析するサンプル コードを記述する必要がある場合 (たとえば、タグを文字どおりに渡すのではなく <em> タグ内のテキストを斜体にする場合など) は、コード ブロックを <pre> タグでラップします。

コピー ボタンを備えたコード ブロック

言語の名前と、コード ブロックの内容をコピーするボタンを含むヘッダーを追加することもできます。

たとえば、次のコードでは、JavaScript の構文の強調表示とコード サンプルのコピー ボタンが追加されます。

コピー ボタンの使用例

```javascript copy
const copyMe = true
```

GitHub Docs でレンダリングされたコードの例

JavaScript
const copyMe = true

コード サンプルの注釈

コード サンプルの注釈は、サンプル コードの横にコメントを注釈としてレンダリングすることで、長いコード例を説明するのに役立ちます。 これにより、コード自体を乱雑にすることなく、コードのより長い説明を記述できます。 注釈を含むコード サンプルは 2 つのペインのレイアウトでレンダリングされ、左側にコード サンプル、右側に注釈が表示されます。 注釈は、コード例の上にカーソルを置いたときに視覚的に強調されます。

コード注釈は、layout: inline frontmatter プロパティを持つ記事でのみ機能します。 コード注釈の記述およびスタイル設定を行う方法について詳しくは、「コード例に注釈を付ける」を参照してください。

注釈付きコード サンプルの例

```yaml annotate
# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $
```

GitHub Docs でコード注釈を使う記事の例については、「GitHub Actionsでのパッケージの公開とインストール」を参照してください。

octicon

octicon は、GitHub のインターフェイス全体で使用されるアイコンです。 ユーザー インターフェイスを文書化するときに octicon を参照し、テーブル内のバイナリ値を示します。 特定の octicon の名前は、octicon のサイトで見つけます。

UI に表示される octicon を参照する場合は、その octicon が UI 要素のラベル全体であるのか (たとえば、"+" のラベルのみが付いているボタン)、または別のラベルに追加する装飾にすぎないのか (たとえば、ボタンに "+ Add message" というラベルが付いている) を確認してください。

  • octicon がラベル全体である場合は、ブラウザーの開発者ツールを使ってその octicon を検査し、代わりにスクリーン リーダーのユーザーが何を聞くかを確認してください。 次に、aria-label にそのテキストを使います (例: {% octicon "plus" aria-label="Add file" %})。 UI では、Octicon 自体に aria-label が含まれておらず、<summary> または <div> タグなどの周囲の要素には含まれていることがあります。
    • ラベルとして使用される一部の Octicon には、UI 要素またはユーザーによる入力の状態に基づいて変化する動的 aria-label 要素があります。 たとえば、2 つのセキュリティ ポリシー Policy A および Policy B が存在するユーザーの場合、UI には 2 つのごみ箱 Octicons が表示され、{% octicon "trash" aria-label="Delete Policy A" %} および {% octicon "trash" aria-label="Delete Policy B" %} とラベル付けされます。 動的 aria-label 要素の場合、ユーザーが遭遇する正確な aria-label 情報を文書化できないため、Octicon とラベルのプレースホルダーの例を記述します (例: "{% octicon "trash" aria-label="The trash icon, labelled 'Delete YOUR-POLICY-NAME'." %}")。 これにより、Octicon とそのラベル付けの方法の両方を識別し、Octicon を視覚的に記述しているユーザーと共同作業するためのコンテキストを提供できます。
  • Octicon が装飾的な場合は、aria-hidden=true 属性を持つスクリーン リーダーに非表示になっている可能性があります。 その場合は、製品との一貫性を保つため、ドキュメントの octicon の Liquid 構文でも aria-hidden="true" を使います (例: "{% octicon "plus" aria-hidden="true" %} Add message")。

octicon を別の方法で使う場合 ("check" アイコンと "x" アイコンを使ってテーブルにバイナリ値を反映するなど) は、aria-label を使って、その octicon の視覚的な特徴ではなく、意味を説明してください。 たとえば、テーブルの "サポート対象" 列に "x" アイコンを使う場合は、aria-label として "サポート対象外" を使用します。 詳しくは、「スタイル ガイド」を参照してください。

Octicons の使用例

{% octicon "<name of Octicon>" %}
{% octicon "plus" %}
{% octicon "plus" aria-label="Add file" %}
"{% octicon "plus" aria-hidden="true" %} Add file"

オペレーティング システム タグ

さまざまなオペレーティング システムに向けたドキュメントを記述する必要がある場合があります。 オペレーティング システムごとに、異なる一連の手順が必要になる場合があります。 オペレーティング システム タグを使うと、オペレーティング システムごとに情報の境界を定めることができます。

オペレーティング システム タグの使用例

{% mac %}

These instructions are pertinent to Mac users.

{% endmac %}

{% linux %}

 These instructions are pertinent to Linux users.

{% endlinux %}

{% windows %}

These instructions are pertinent to Windows users.

{% endwindows %}

記事の YAML frontmatter で既定のプラットフォームを定義できます。 詳しくは、「YAML front matter の使用」を参照してください。

ツール タグ

場合によっては、ツールごとに異なる手順を含むドキュメントを記述する必要があります。 たとえば、GitHub UI、GitHub CLI、GitHub Desktop、GitHub Codespaces、Visual Studio Code では、異なる手順により同じタスクを実行できる場合があります。 ツールごとに表示する情報を分けるには、ツール タグを使用します。

GitHub Docs には、GitHub の製品といくつかのサードパーティ製拡張機能用ツール タグが含まれています。 サポートされているすべてのツールの一覧については、github/docs リポジトリ内の all-tools.js オブジェクトを参照してください。

まれに、新しいツールを追加することがあります。 新しいツールを追加する前に、「記事でのツール スイッチャーの作成」をお読みください。 新しいツールを追加するには、lib/all-tools.js 内の allTools オブジェクトに、キーと値のペアとしてエントリを追加します。 キーには、記事内でそのツールを参照するために使うタグを指定し、値には、記事の先頭にあるツール ピッカーでどのようにそのツールを識別するかを指定します。

YAML frontmatter で記事の既定のツールを定義できます。 詳しくは、「YAML front matter の使用」を参照してください。

ツール タグの使用例

{% api %}

These instructions are pertinent to API users.

{% endapi %}

{% bash %}

These instructions are pertinent to Bash shell commands.

{% endbash %}

{% cli %}

These instructions are pertinent to GitHub CLI users.

{% endcli %}

{% codespaces %}

These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used.

{% endcodespaces %}

{% curl %}

These instructions are pertinent to curl commands.

{% endcurl %}

{% desktop %}

 These instructions are pertinent to GitHub Desktop.

{% enddesktop %}

{% importer_cli %}

These instructions are pertinent to GitHub Enterprise Importer CLI users.

{% endimporter_cli %}

{% javascript %}

These instructions are pertinent to javascript users.

{% endjavascript %}

{% jetbrains %}

These instructions are pertinent to users of JetBrains IDEs.

{% endjetbrains %}

{% powershell %}

These instructions are pertinent to `pwsh` and `powershell` commands.

{% endpowershell %}

{% vscode %}

These instructions are pertinent to VS Code users.

{% endvscode %}

{% webui %}

These instructions are pertinent to GitHub UI users.

{% endwebui %}

テキストの再利用可能な文字列と変数文字列

再利用可能な文字列 (一般にコンテンツ参照または conref と呼ばれます) には、ドキュメント内の複数の場所で使用されるコンテンツを含めます。 これらを作成すると、文字列が表示されるすべての場所ではなく、1 つの場所でコンテンツを更新できます。

長い文字列の場合は再利用可能を使い、短い文字列の場合は変数を使います。 再利用可能と変数について詳しくは、「再利用可能なコンテンツの作成」を参照してください。

テーブル パイプ

GitHub Docs 内のテーブルのすべての行は、Liquid バージョン管理のみを含む行であっても、| パイプ記号で開始まり、パイプ記号で終わる必要があります。

| Where is the table located? | Does every row end with a pipe? |
| --- | --- |
| {% ifversion some-cool-feature %} |
| GitHub Docs | Yes |
| {% endif %} |

テーブル行ヘッダー

最初の列にテーブル行のヘッダーが含まれるテーブルを作成する場合は、Liquid タグ {% rowheaders %} {% endrowheaders %} でテーブルをラップします。 テーブルのマークアップを使う方法について詳しくは、「スタイル ガイド」を参照してください。

行ヘッダーを含むテーブルの例

{% rowheaders %}

|             | Mona | Tom    | Hobbes |
|-------------|------|--------|--------|
|Type of cat  | Octo | Tuxedo | Tiger  |
|Likes to swim| Yes  | No     | No     |

{% endrowheaders %}

行ヘッダーのないテーブルの例

| Name   | Vocation         |
| ------ | ---------------- |
| Mona   | GitHub mascot    |
| Tom    | Mouse antagonist |
| Hobbes | Best friend      |

コード ブロックを含むテーブル

コード ブロックなどのブロック アイテムを含むテーブルを使うことは一般的には推奨されませんが、場合によっては適切なこともあります。

GitHub Flavored Markdown のテーブルには改行やブロック レベル構造を含めることができないため、HTML タグを使ってテーブル構造を記述する必要があります。

HTML テーブルにコード ブロックが含まれている場合、テーブルの幅がページ コンテンツの通常の幅を超え、通常は小さい目次が含まれている領域にオーバーフローする可能性があります。

その場合は、次の CSS スタイルを <table> HTML タグに追加します。

<table style="table-layout: fixed;">

この使用法の現在の例については、「ユース ケースと例」を参照してください。

docs リポジトリ内のドキュメントへのリンクは、製品 ID (例、/actions、/admin) で始まり、ファイルパス全体を含む必要がありますが、ファイル拡張子は含まれません。 たとえば、/actions/creating-actions/about-custom-actions のようにします。

画像のパスは、/assets で始まり、ファイル拡張子を含むファイルパス全体が含まれている必要があります。 たとえば、/assets/images/help/settings/settings-account-delete.png のようにします。

Markdown ページへのリンクは、サーバー側で現在のページの言語とバージョンに合わせていくつかの変換を行います。 これらの変換の処理は、lib/render-content/plugins/rewrite-local-links に記述されています。

以下は、コンテンツ ファイルに次のリンクを含める場合です。

/github/writing-on-github/creating-a-saved-reply

GitHub.com で表示すると、リンクは言語コードでレンダリングされます。

/en/github/writing-on-github/creating-a-saved-reply

GitHub Enterprise Server ドキュメントで表示すると、バージョンも含まれます。

/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply

リンクについて詳しくは、「スタイル ガイド」をご覧ください。

サイトは動的であるため、記事の異なるバージョンごとに HTML ファイルをビルドすることはありません。 代わりに、記事のすべてのバージョンに対して「パーマリンク」が生成されます。 これは、記事のversions frontmatter.に基づいて行います。

Note

2021 年初頭の時点では、free-pro-team@latest バージョンは URL に含まれていません。 lib/remove-fpt-from-path.js というヘルパー関数が、URL からバージョンを削除します。

たとえば、現在サポートされているバージョンで利用可能な記事には、次のようなパーマリンク URL があります。

  • /en/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-cloud@latest/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.10/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.9/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.8/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.7/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.6/get-started/getting-started-with-git/set-up-git

GitHub Enterprise Server で使用できない記事には、パーマリンクが 1 つだけ含まれます。

  • /en/get-started/getting-started-with-git/set-up-git

Note

コンテンツ投稿者の場合は、ドキュメントへのリンクを追加するときに、サポートされているバージョンについて心配する必要はありません。 上記の例に従って、記事を参照する場合は、その相対位置を使用できます： /github/getting-started-with-github/set-up-git

別の GitHub Docs ページにリンクする場合は、[]() などの標準の Markdown 構文を使いますが、ページ タイトルの代わりに AUTOTITLE と入力します。 GitHub Docs アプリケーションによって、レンダリング中に AUTOTITLE がリンクされたページのタイトルに置き換えられます。 この特別なキーワードでは大文字と小文字が区別されるため、入力には注意してください。そうでないと、置換が機能しません。

  • For more information, see "[AUTOTITLE](/path/to/page)."
  • For more information, see "[AUTOTITLE](/path/to/page#section-link)."
  • For more information, see the TOOLNAME documentation in "[AUTOTITLE](/path/to/page?tool=TOOLNAME)."

Note

同じページのセクションのリンクは、このキーワードでは機能しません。 代わりに、完全なヘッダー テキストを入力してください。

別のバージョンのドキュメントの現在の記事へのリンク

場合によっては、ある記事から別の製品バージョンの同じ記事にリンクすることが必要になる場合があります。 次に例を示します。

  • 無料プラン、プロ プラン、またはチーム プランで使用できない機能について説明し、同じページの GitHub Enterprise Cloud バージョンにリンクする必要があります。
  • 記事の GitHub Enterprise Server バージョンでは、そのバージョンに付属している機能について説明していますが、サイト管理者は、GitHub Enterprise Cloud で使用されている最新バージョンの機能にアップグレードできます。

currentArticle プロパティを使用して、別のバージョンのページに直接リンクできます。 つまり、記事の URL が変更された場合でも、リンクは引き続き直接機能します。

{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest{{ currentArticle }}).{% endif %}

変換の防止

Enterprise コンテンツの Dotcom のみの記事にリンクする必要があり、リンクを Enterprise 化したくない場合があります。 変換を回避するには、パスに優先バージョンを含める必要があります。

"[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)"

コンテンツの正規のホームがドキュメント サイトの外部に移動することがあります。 書き換えに含まれている src/redirects/lib/external-sites.json リンクはありません。 この種類のリダイレクトの詳細については、contributing/redirects.md を参照してください。

ドキュメントには、/article/article-name、/github/article-name のような従来のファイルパスを使用するリンクが含まれています。 このドキュメントには、過去の名前で記事を参照するリンクも含まれています。 これらのリンクの種類はどちらもリダイレクトにより正しく機能しますが、バグです。

記事へのリンクを追加するときは、現在のファイルパスと記事名を使用します。