GitHub Docs での Markdown と Liquid の使用

で Markdown と Liquid を使用する方法について GitHub Docs

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 に表示される例のリスト

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

リスト内の別の段落です。
次のアイテムです。

警告

アラートは、ユーザーが知っておく必要がある重要な情報が強調表示されます。サポートされているアラートの種類、Markdown でのアラートの書式設定方法、アラートを使うタイミングの詳細については、「スタイルガイド」を参照してください。

アラートの例

> [!TIP]
> Try this out!

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

GitHub Docs に表示されるアラートの例

ヒント

これを試してみましょう。

メモ

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

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

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

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

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

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

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

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

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

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

コピーボタンの使用例

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

GitHub Docs に表示されるコード例

JavaScript

const copyMe = true

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でのパッケージの公開とインストールを参照してください。

Copilot プロンプト

Copilotのプロンプトは、ブロックで表示することも、テキスト内にインラインで含めることもできます。

プロンプトブロック

これらはコードブロックとよく似ていますが、プログラミング言語の名前ではなく copilot キーワードを使います。

プロンプトブロックには常にコピーボタンが必要であり、copy オプションを使用して追加されます。また、Copilot オプションを使用して追加されたprompt ボタンもあります。 [Copilot] ボタンを使用すると、リーダーはコパイロットチャットのGitHub.comでプロンプトをすばやく実行できます。オプション copy と prompt は任意の順序で使用できます。

Copilotボタンとコピーボタンを含むプロンプトブロックの例

```copilot prompt copy
What is git?
```

これは次のように表示されます。

Copilot prompt

What is git?

What is git?

What is git?

次の場合にのみ、 Copilot ボタンをプロンプトブロックに追加する必要があります。

プロンプトは、(上記の例のように) 追加のコンテキストなしで実行できます。
同じ記事内に、プロンプトに必要なコンテキストを提供するコードブロックがあります。

プロンプトにコンテキストを含める

Copilot ボタンを使用する場合は、同じ記事のコードブロックを参照することで、コパイロットチャットに送信されるプロンプトにコンテキストを追加できます。これを行うには、コードブロックに id=STRING-OF-YOUR-CHOICE を追加し、プロンプトブロックに ref=STRING-OF-YOUR-CHOICE を追加します。

プロンプトブロック内のコンテキストとして使われるコードブロックの例

Add an id to the code block whose code you want to add to the prompt as context:

```javascript id=js-age
function logPersonsAge(a, b, c) {
  if (c) {
    console.log(a + " is " + b + " years old.");
  } else {
    console.log(a + " does not want to reveal their age.");
  }
}
```

Then, elsewhere in the same article, reference the id in the prompt block:

```copilot copy prompt ref=js-age
Improve the variable names in this function
```

Copilot Cookbook には、コンテキストを含むプロンプトブロックの例が多数あります。たとえば、「コードの読みやすさと保守容易性を改良する」を参照してください。

インラインプロンプト

ほとんどのインラインプロンプトでは、インラインコードと同様に、バックティックを使ってマークします。

プロンプトにコンテキストが不要な場合は、プロンプトの後にクリック可能な Copilot アイコンを追加できます。これにより、読者はコパイロットチャット上のGitHub.comでプロンプトを実行できます。クリック可能なアイコンを追加するには、プロンプトを Liquid 構文タグで囲みます。

... you can click {% prompt %}what is git{% endprompt %} to run this ...

これは次のように表示されます。

... Git とはをクリックすると、これを実行できます。

Octicons

オクチコンは、 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 要素があります。たとえば、Policy A と Policy B という 2 つのセキュリティポリシーがある場合、UI には {% octicon "trash" aria-label="Delete Policy A" %} と {% octicon "trash" aria-label="Delete Policy B" %} というラベルが付いた 2 つのごみ箱 Octicon が表示されます。動的 aria-label 要素の場合、ユーザーが遭遇する正確な aria-label 情報を文書化できないため、Octicon とラベルのプレースホルダーの例を記述します (例: "{% octicon "trash" aria-label="The trash icon, labeled '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 製品および選択したサードパーティ製拡張機能のツールタグが保持されます。サポートされているすべてのツールの一覧については、all-tools.ts リポジトリ内のオブジェクトを参照してください。

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

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

この使用法の最新の例については、「GitHub Actions を使って作業を管理する」をご覧ください。

リンク

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 Docsで表示すると、リンクは言語コードでレンダリングされます。

/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.に基づいて行います。

メモ

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

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

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

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

/en/get-started/git-basics/set-up-git

メモ

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

AUTOTITLE を使用した内部リンク

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

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

メモ

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

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

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

無料プラン、プロプラン、またはチームプランで使用できない機能について説明し、同じページの 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 のような従来のファイルパスを使用するリンクが含まれています。このドキュメントには、過去の名前で記事を参照するリンクも含まれています。これらのリンクの種類はどちらもリダイレクトにより正しく機能しますが、バグです。

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

GitHub Docs での Markdown と Liquid の使用

この記事で