YAML front matter の使用

YAML frontmatter について

YAML frontmatter は、Jekyll によって普及しているオーサリング規則であり、ページにメタデータを追加するのに使えます。これは、GitHub Docs 内のすべての Markdown ファイルの先頭に存在する、キー値コンテンツのブロックです。詳しくは、frontmatter のドキュメントを参照してください。

YAML frontmatter の値

次の frontmatter の値には、GitHub Docs の特別な意味と要件があります。また、すべてのページの frontmatter を検証するためにテストスイートが使用するスキーマもあります。詳細については、lib/frontmatter.jsを参照してください。

versions
redirect_from
title
shortTitle
intro
permissions
product
layout
children
childGroups
featuredLinks
showMiniToc
allowTitleToDifferFromFilename
changelog
defaultPlatform
defaultTool
learningTracks
includeGuides
type
topics
communityRedirect
effectiveDate

`versions`

目的: ページが適用されるバージョンを示します。さまざまな種類のバージョン管理の詳細については、「バージョン管理のドキュメント」を参照してください。
型: Object 許容されるキーは製品名にマップされ、lib/frontmatter.js の versions オブジェクト内にあります。
この frontmatter 値は、現在、すべてのページに必要です。
* は、該当バージョンのすべてのリリースを示すために使用されます。
すべての index.md ファイルに存在する必要がありますが、実際の値は子に基づいて実行時に計算されます。

この frontmatter 値は、ドキュメントサイトで記事の各バージョンに対して "permalinks" を生成するために使用されます。詳細については、Permalinks を参照してください。

Free, Pro, & Team および GitHub Enterprise Server バージョン 3.11 以降に適用される例:

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'

GitHub Enterprise Server にのみ適用される例:

title: Downloading your license
versions:
  ghes: '*'

また、リリースの範囲に対してページをバージョン管理することもできます。これは、Free, Pro, & Team および GitHub Enterprise Server バージョン 3.1、3.2 のみのページをバージョン管理しています。

versions:
  fpt: '*'
  ghes: '>=3.1 <3.3'

`redirect_from`

目的: このページにリダイレクトする URL を一覧表示します。
型: Array
省略可能

例:

title: Getting started with GitHub Desktop
redirect_from:
  - /articles/first-launch
  - /articles/error-github-enterprise-version-is-too-old
  - /articles/getting-started-with-github-for-windows

詳しくは、「リダイレクトを構成する」を参照してください。

`title`

目的: レンダリングされたページの <title> タグで使用するわかりやすいタイトルと、ページの上部にある h1 要素を設定します。
型: String
省略可能。省略した場合、ページ <title> は引き続き設定されます。ただし、GitHub.com、 GitHub Enterprise のようなジェネリック値を使用します。

`shortTitle`

目的: 階層リンクとナビゲーション要素で使用するのページタイトルの省略形。
型: String
省略可能。省略した場合は、 title が使用されます。

記事の種類	最大文字数
記事	31
categories	27
マップトピック	30

例:

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

`intro`

目的: ページの概要を設定します。この文字列は title の後にレンダリングされます。
型: String
省略可能。

`permissions`

目的: 記事のアクセス許可ステートメントを設定します。この文字列は intro の後にレンダリングされます。
型: String
省略可能。

`product`

目的: 記事の製品コールアウトを設定します。この文字列は intro と permissions ステートメントの後にレンダリングされます。
型: String
省略可能。

`layout`

目的: 適切なページレイアウトをレンダリングします。
型: レイアウトの名前と一致する String。 components/landing 名付けられたレイアウトの場合、値は product-landing となります。
省略可能。省略した場合、DefaultLayout が使われます。

`children`

目的: product/category/map トピックに属する相対リンクを一覧表示します。詳細については、「インデックスページ」を参照してください
次のコマンドを入力します: Array 既定値は false です。
index.md ページで必須

`childGroups`

目的: 子をホームページ上のグループにレンダリングします。詳細については、「Homepage」を参照してください。
次のコマンドを入力します: Array 既定値は false です。
ホームページ index.md で必須

`featuredLinks`

目的: リンクされた記事のタイトルと紹介を製品のランディングページとホームページに表示します。
次のコマンドを入力します: Object
省略可能。

人気のあるリンクの一覧は、ランディングページ上でタイトル「Popular」の下に表示されるリンクです。または、 featuredLinks.popularHeading プロパティを新しい文字列に設定し、「Popular」というタイトルをカスタマイズすることもできます。

例:

featuredLinks:
  gettingStarted:
    - /path/to/page
  startHere:
    - /guides/example
  popular:
    - /path/to/popular/article1
    - /path/to/popular/article2
  popularHeading: An alternate heading to Popular

`showMiniToc`

目的: 記事の残りのコンテンツの上にミニ目次 (TOC) を表示するかどうかを示します。詳しくは、「自動生成されたミニ TOC」を参照してください。
次のコマンドを入力します: Boolean 既定値は記事では true で、マップトピックと index.md ページでは false です。
省略可能。

`allowTitleToDifferFromFilename`

目的: ページがファイル名と異なるタイトルを持つことを許可するかどうかを示します。たとえば、content/rest/reference/orgs.md は Orgs ではなく Organizations というタイトルです。 frontmatter が true に設定されているページは、テストでフラグが設定されたり、src/content-render/scripts/reconcile-filenames-with-ids.js によって更新されたりすることはありません。
次のコマンドを入力します: Boolean 既定値は false です。
省略可能。

`changelog`

目的: 製品のランディングページ (components/landing) に GitHub Changelog からプルされた項目の一覧をレンダリングします。 1 つの例外は Education で、https://github.blog/category/community/education からプルします。
型: Object、プロパティ。
- label -- 必須であり、GitHub Changelog で使用されるラベルに対応している必要があります
- prefix -- 省略可能な文字列。各変更ログタイトルの、ドキュメントフィードでは省略する開始文字を示します。たとえば、プレフィックス GitHub Actions: を指定すると、changelog タイトルが GitHub Actions: Some Title Here の場合、ドキュメントフィードでは Some Title Here とレンダリングされます。
省略可能。

`defaultPlatform`

目的: ページの最初のプラットフォーム選択をオーバーライドします。この frontmatter を省略すると、閲覧者のオペレーティングシステムに一致するプラットフォーム固有のコンテンツが既定で表示されます。この動作は、個々のページに対して変更でき、手動で選択する方が適切です。たとえば、ほとんどの GitHub Actions ランナーは Linux を使用しており、そのオペレーティングシステムは閲覧者のオペレーティングシステムに依存しません。
型: String。次のいずれかです: mac、windows、linux
省略可能。

例:

defaultPlatform: linux

`defaultTool`

目的: ページの初期のツール選択をオーバーライドします。このツールは、閲覧者が GitHub (GitHub.com の Web UI、GitHub CLI、GitHub Desktop など) または GitHub API を操作するために使用しているアプリケーションを参照します。ツールセレクターについて詳しくは、「GitHub Docs での Markdown と Liquid の使用」をご覧ください。この frontmatter を省略すると、GitHub Web UI に一致するツール固有のコンテンツが既定で表示されます。ユーザーが (ツールタブをクリックして) ツールのユーザー設定を行った場合は、既定値ではなくそのユーザー設定が適用されます。
型: String。次のいずれかです: webui、cli、desktop、curl、codespaces、vscode、importer_cli、graphql、powershell、bash、javascript
省略可能。

defaultTool: cli

`learningTracks`

目的: 製品のサブランディングページに学習トラックの一覧を表示します。
次のコマンドを入力します: String これは、data/learning-tracks/*.yml で定義されている学習トラックの名前を参照します。
省略可能

Note

おすすめトラックは、学習トラック YAML の特定のプロパティによって設定されます。詳しくは、README をご覧ください。

`includeGuides`

目的: 記事の一覧をレンダリングします。type と topics でフィルターできます。 layout: product-guides と共に使用された場合にのみ適用されます。
型: Array
省略可能。

例:

includeGuides:
  - /actions/guides/about-continuous-integration
  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
  - /actions/guides/building-and-testing-nodejs
  - /actions/guides/building-and-testing-powershell

`type`

目的: 記事の種類を示します。
型: String。次のいずれかです: overview、quick_start、tutorial、how_to、reference、rai
省略可能。

`topics`

目的: この記事の対象となるトピックを示します。トピックの追加の詳細については、コンテンツモデルを参照してください。既存のトピックの完全な一覧は、許可トピック一覧ファイルにあります。記事の frontmatter のトピックと許可トピックの一覧が同期しなくなった場合、トピック CI テストは失敗します。
型: String の配列です
省略可能: トピックは各記事で推奨されますが、既存の記事にまだトピックがない場合や、新しい記事にトピックを追加してもあまり意味がない場合があります。

`communityRedirect`

目的: フッター内のカスタムリンクと、Ask the GitHub community リンクの名前を設定します。
次のコマンドを入力します: Object プロパティは name と href です。
省略可能。

`effectiveDate`

目的: サービス使用条件に関する記事の発効日を設定して、エンジニアリングチームがユーザーに条項の確認を自動的に求め直すことができるようにする
型: string YEAR-MONTH-DAY (例: 2021-10-04 は 2021 年 10 月 4 日)
省略可能。

Note

effectiveDate frontmatter 値は、GitHub スタッフのみが使用します。

単一引用符のエスケープ

YAML frontmatter で、単一引用符が 1 つ表示されている (') はずの場所に 2 つの単一引用符が連続している場合 ('')、それは YAML で単一引用符をエスケープする際の推奨方法です。

別の方法として、frontmatter フィールドを囲む単一引用符を二重引用符に変更し、内部の単一引用符をエスケープせず残すこともできます。

自動生成されたミニ TOC

すべての記事には、ミニ目次 (TOC) が表示されます。これは、自動生成された、記事内のすべての H2 へのリンクが含まれる「この記事の内容」セクションです。ミニ TOC には H2 ヘッダーのみが含まれます。特定のセクションのみが特定のタスクに関連するよう情報を分割するために、記事で H3 または H4 ヘッダーを使用する場合は、セクション TOC を使用すると、ユーザーが最も関連性の高いコンテンツに移動できます。

showMiniToc frontmatter 値を false に設定すると、ミニ TOC が記事に表示されないようにすることができます。

ミニ TOC は、製品のランディングページ、カテゴリのランディングページ、またはマップトピックページには表示されません。

Markdown ソースにハードコードされた「この記事の内容」セクションを追加しないでください。追加すると、ページに重複したミニ TOC が表示されます。

ファイル名

新しい記事を追加するときは、ファイル名が、記事の title frontmatter で使用するタイトルの kebab ケースバージョンであることを確認します。タイトルに句読点 (「GitHub's Billing Plans」など) がある場合、これは難しい場合があります。テストでは、タイトルとファイル名の不一致にフラグが設定されます。特定の記事のこの要件をオーバーライドするには、allowTitleToDifferFromFilename frontmatter を追加します。

インデックスページ

インデックスページは、ドキュメントサイトの目次ファイルです。すべての製品、カテゴリ、およびマップトピックサブディレクトリには、コンテンツの概要とすべての子記事へのリンクを提供する index.md ファイルがあります。各 index.md には、製品、カテゴリ、マップトピックの子ページへの相対リンクのリストを持つ children frontmatter プロパティが必要です。インデックスページには、versions フロントマッタープロパティが必要であり、実際の値は子記事のバージョンに基づいて実行時に計算されます。

Note

サイトは、children frontmatter に含まれるパスについてのみ認識します。ディレクトリまたは記事が存在していてもchildren に含まれていない場合、そのパスは 404 を返します。

Homepage

ホームページは、ドキュメントサイトのメインの目次ファイルです。ホームページには、すべてのインデックスページと同様に完全な children リストが必要ですが、メインコンテンツ領域で強調表示される childGroups frontmatter プロパティも指定する必要があります。

childGroups は、グループの name、グループの icon (省略可能)、children の配列を含む、マッピングの配列です。 children frontmatter プロパティには、配列内の children が必要です。

新しい製品ガイドページの作成

製品ガイドページを作成するには (GitHub Actions ガイドページ) など)、既存の markdown ファイルを、次の frontmatter 値で作成または変更します。

layout: product-guides を参照し、製品ガイドページテンプレートを使用します。
learningTracks に学習トラックを含めます。省略可能。
includeGuides とともに含める記事を定義します。省略可能。

学習トラックを使用する場合は、data/learning-tracks/*.yml で定義する必要があります。 includeGuides を使用する場合は、この一覧の各記事の frontmatter に topics および type があることを確認します。