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 を参照してください。

以下は GitHub.com および、最近の GitHub Enterprise Server バージョンに当てはまる例です。

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

以下は GitHub Enterprise Server のサポートされているバージョン全てに当てはまりますが、GitHub.com には該当しません。

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

また、リリースの範囲に対してページをバージョン管理することもできます。 これは、GitHub.com および、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
カテゴリ	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 で定義されている学習トラックの名前を参照します。
• 省略可能

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

• 目的: この記事の対象となるトピックを示します。 このトピックは、一部のランディング ページのガイドをフィルター処理するために使用されます。 たとえば、「GitHub Actions のガイド」の下部にあるガイドはトピックでフィルター処理でき、トピックはガイドの概要の下に一覧表示されます。 トピックの追加の詳細については、コンテンツ モデルを参照してください。 既存のトピックの完全な一覧は、許可トピック一覧ファイルにあります。 記事の frontmatter のトピックと許可トピックの一覧が同期しなくなった場合、トピック CI テストは失敗します。
• 型: String の配列です
• 省略可能: トピックは各記事で推奨されますが、既存の記事にまだトピックがない場合や、新しい記事にトピックを追加してもあまり意味がない場合があります。

communityRedirect

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

effectiveDate

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

単一引用符のエスケープ

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 フロントマッター プロパティが必要であり、実際の値は子記事のバージョンに基づいて実行時に計算されます。

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 があることを確認します。