YAML front matter の使用

YAML frontmatter について

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

YAML frontmatter の値

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

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

versions

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

この 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 を一覧表示します。
• 型:
• 省略可能

例:

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

詳しくは、「AUTOTITLE」をご覧ください。

title

• 目的: レンダリングされたページの タグで使用するわかりやすいタイトルと、ページの上部にある 要素を設定します。
• 型:
• 必須。

shortTitle

• 目的: パンくずリストやナビゲーション要素で使用するための、ページ タイトルの短縮版。
• 型:
• 省略可能。 省略した場合は、 が使用されます。

記事の種類	最大文字数
記事	31
カテゴリー	27
マップ トピック	30

例:

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

intro

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

permissions

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

product

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

layout

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

children

• 目的: product/category/map トピックに属する相対リンクを一覧表示します。 詳細については、「インデックス ページ」を参照してください
• データ型: 既定値は です。
• ページで必須です。

childGroups

• 目的: 子をホーム ページ上のグループにレンダリングします。 詳細については、「Homepage」を参照してください。
• データ型: 既定値は です。
• ホームページに必要です。

featuredLinks

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

人気のあるリンクの一覧は、ランディング ページ上でタイトル「Popular」の下に表示されるリンクです。 または、 プロパティを新しい文字列に設定し、「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」を参照してください。
• データ型: 既定値は、記事ではで、マップトピックとページではです。
• 省略可能。

allowTitleToDifferFromFilename

• 目的: ページがファイル名と異なるタイトルを持つことを許可するかどうかを示します。 たとえば、 は ではなく というタイトルです。 frontmatter が に設定されているページは、テストでフラグが設定されたり、 によって更新されたりすることはありません。
• データ型: 既定値は です。
• 省略可能。

changelog

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

defaultPlatform

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

例:

defaultPlatform: linux

defaultTool

• 目的: ページの最初のツール選択をオーバーライドします。このツールは、リーダーがGitHub (GitHub.com の Web UI、GitHub CLI、GitHub Desktop など) またはGitHub API を操作するために使用しているアプリケーションを参照します。 ツール セレクターについて詳しくは、「AUTOTITLE」をご覧ください。 このフロントマッターを省略すると、GitHub Web UI に一致するツール固有のコンテンツが既定で表示されます。 ユーザーが (ツール タブをクリックして) ツールのユーザー設定を行った場合は、既定値ではなくそのユーザー設定が適用されます。
• 型: 、、、、、、、、、、、 のいずれかです。
• 省略可能。

defaultTool: cli

learningTracks

• 目的: 製品のサブランディング ページに学習トラックの一覧を表示します。
• データ型: これは、 で定義されている学習トラックの名前を参照します。
• 省略可能

includeGuides

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

例:

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

journeyTracks

• 目的: ジャーニーのランディング ページ用のジャーニーを定義します。
• 型: 次のプロパティを持つオブジェクト。
  • (必須): ジャーニーの一意識別子。 ID は、1 つの体験ランディング ページ内の体験に対してのみ一意である必要があります。
  • (必須): 体験のタイトルを表示する (Liquid 変数をサポート)
  • (省略可能): 体験の説明 (Liquid 変数をサポート)
  • (必須): この体験を構成するガイド オブジェクトの配列。 各ガイドオブジェクトには次の要素があります。
  • (必須): 記事へのパス
  • (省略可能): ユーザーを体験の代替パスに導くカスタム テキスト。 Liquid 変数と をサポートします。
• と共に使用された場合にのみ適用されます。
• 省略可能。

例:

journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    guides:
      - href: '/actions/quickstart'
      - href: '/actions/learn-github-actions'
        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
      - href: '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
      - href: '/actions/deployment/deploying-with-github-actions'

type

• 目的: 記事の種類を示します。
• 型: 次のいずれかの型です: 、 、 、 、 、 、 。
• 省略可能。

communityRedirect

• 目的: フッターの Ask the GitHub community リンクのカスタム リンクとリンク名を設定します。
• データ型: プロパティは、および です。
• 省略可能。

effectiveDate

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

単一引用符をエスケープ処理する

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

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

自動生成されたミニ TOC

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

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

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

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

ファイル名

新しい記事を追加する際は、記事の frontmatter で使用するタイトルをケバブケースにしたものをファイル名にし。 タイトルに句読点 ("GitHub の課金プラン" など) がある場合、これは難しい場合があります。 テストでは、タイトルとファイル名の不一致にフラグが設定されます。 特定の記事のこの要件をオーバーライドするには、 frontmatter を追加します。

インデックス ページ

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

ホームページ

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

は、グループのマッピングを含む配列であり、そのグループの任意の で、 の配列です。 配列内の要素はfrontmatterプロパティに存在している必要があります。

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

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

• を参照し、product guides page テンプレートを使用します。
• に学習トラックを含めます。 省略可能。
• とともに含める記事を定義します。 省略可能。

学習トラックを使用する場合は、 で定義する必要があります。 を使用する場合は、この一覧の各記事の frontmatter に および があることを確認します。