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
で定義されている学習トラックの名前を参照します。 - 省略可能
注: おすすめトラックは、学習トラック 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 日) - 省略可能。
注: 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
フロントマッター プロパティが必要であり、実際の値は子記事のバージョンに基づいて実行時に計算されます。
注: サイトは、 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
があることを確認します。