Skip to main content

コンテンツ リンターの使用

コンテンツ リンターを使って、コントリビューションのエラーをチェックできます。

GitHub Docs コンテンツ リンターについて

コンテンツ リンターでは、Markdown コンテンツのスタイル ガイド ルールが適用されます。

リンターでは、markdownlint をフレームワークとして使ってチェックを実行し、欠陥を報告し、可能な場合はコンテンツを自動的に修正します。 このフレームワークは、柔軟に特定のルールを実行し、わかりやすいエラー メッセージを提供し、エラーを修正することができます。 GitHub Docs コンテンツ リンターは、いくつかの既存の markdownlint ルールと追加のカスタム ルールを使って、content ディレクトリと data ディレクトリ内の Markdown コンテンツをチェックします。 カスタム ルールでは、markdownlint フレームワークでまだ使用できないチェックか、GitHub Docs コンテンツに固有のチェックを実装します。 ルールによって、Markdown と Liquid の両方の構文がチェックされます。

GitHub Docs コンテンツ リンターの実行

GitHub Docs コンテンツ リンターは、事前コミット時に自動的に実行されますが、手動で実行することもできます。

事前コミット時にリンターを自動的に実行する

ローカルでコンテンツを記述し、コマンド ラインを使ってファイルをコミットすると、それらのステージングされたファイルはコンテンツ リンターによって自動的にリンティングされます。 警告とエラーの両方が報告されますが、コミットの完了を妨げるのはエラーのみです。

エラーが報告された場合、コミットは完了しません。 報告されたエラーを修正し、変更したファイルを再追加して、変更を再度コミットする必要があります。 報告されたエラーはすべて修正して、GitHub Docs スタイル ガイドに違反するエラーがコンテンツに含まれないようにする必要があります。 警告が報告された場合は、必要に応じて修正するかどうかを選択できます。

コンテンツをローカルで記述する場合、コマンド ラインで自動的に修正できるルールがいくつかあります。 修正できるエラーを自動的に修正するには、「Automatically fix errors that can be fixed」を参照してください。

GitHub UI でファイルを編集している場合、コミット時にリンターを自動的に実行することはできません。コンテンツがルールに違反している場合は、重大度が error で CI エラーが発生します。

リンターを手動で実行する

ステージングされたファイルと変更されたファイルに対してリンターを実行する

次のコマンドを使って、ステージングされたファイルと変更されたファイルに対してリンターをローカルで実行します。 warningerror 両方の重大度の欠陥が出力されます。

npm run lint-content

ステージングされたファイルと変更されたファイルに対してリンターを実行し、エラーのみを報告する

次のコマンドを使ってステージングされたファイルと変更されたファイルに対してリンターをローカルで実行すると、重大度 error の欠陥だけが報告されます。

npm run lint-content -- --errors

特定のファイルまたはディレクトリに対してリンターを実行する

次のコマンドを使うと、特定のファイルまたはディレクトリに対してリンターをローカルで実行できます。 複数のパスはスペースで区切ってください。 ファイルとディレクトリの両方を同じコマンドに含めることができます。

Shell
npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

修正できるエラーを自動的に修正する

エラーの説明に fixable: true が指定されている場合は、次のコマンドを使って自動的に修正できます。

次のコマンドを実行すると、ステージングされたファイルと変更されたファイルだけが修正されます。

npm run lint-content -- --fix

次のコマンドを実行すると、特定のファイルまたはディレクトリだけが修正されます。

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

リンター ルールの特定のセットを実行する

以下のコマンドを使うと、1 つ以上の特定のリンター ルールを実行できます。 これらの例では、heading-increment ルールと code-fence-line-length ルールが実行されます。 heading-increment code-fence-line-length を、実行する 1 つ以上のリンターの別名に置き換えてください。 このオプションに渡すことができるリンター ルールの一覧を表示するには、npm run lint-content -- --help を実行します。 リンター ルールの短い名前 (例: MD001) または長い名前 (例: heading-increment) を使用できます。

すべてのステージングされたファイルと変更されたファイルに対して、指定したリンター ルールを実行します。

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

特定のファイルまたはディレクトリに対して、指定したリンター ルールを実行します。

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

コミット フックをバイパスする

リンターが導入していないエラーをキャッチした場合は、変更をコミットするときに--no-verify オプションを 使用して git コミット フックをバイパスできます。

git commit -m 'MESSAGE' --no-verify

コンテンツ リンター スクリプトのヘルプ メニューを表示する

npm run lint-content -- --help

リンティング ルール

各ルールは src/content-linter/style 内のファイルで構成されます。ここで、ルールの重大度が定義されます。

変更を main ブランチにマージする前に、エラーを解決する必要があります。 警告を解決する必要がありますが、変更が main ブランチにマージされるのを妨げるものではありません。 コンテンツに警告違反がなくなると、ほとんどのルールは最終的にエラーに昇格します。

ルール IDルール名説明Severityタグ
MD001heading-increment見出しレベルは、一度に 1 レベルだけ増分する必要がありますエラーheadings
MD004ul-style順不同のリストスタイルエラーbullet、ul
MD009no-trailing-spaces末尾のスペースエラーwhitespace
MD011no-reversed-links逆リンク構文エラーリンク
MD012no-multiple-blanks連続する複数の空白行エラー空白文字、blank_lines
MD014commands-show-output出力を表示しないコマンドの前に使用するドル記号エラーcode
MD018no-missing-space-atxatx スタイルの見出しでハッシュの後にスペースがありませんエラーheadings,atx, spaces
MD019no-multiple-space-atxatx スタイルの見出しでハッシュの後に複数のスペースがありますエラーheadings,atx, spaces
MD022blanks-around-headings見出しは空白行で囲む必要がありますエラーheadings, blank_lines
MD023heading-start-left見出しは行の先頭から始まる必要がありますエラーheadings, spaces
MD027no-multiple-space-blockquoteブロック引用記号の後に複数のスペースがありますエラーblockquote、空白、インデント
MD029ol-prefix順序指定済みリスト アイテムのプレフィックスエラーol
MD030list-marker-spaceリスト マーカーの後のスペースエラーol、ul、空白
MD031blanks-around-fencesフェンスされたコード ブロックは空白行で囲む必要があります。エラーコード、blank_lines
MD037no-space-in-emphasis強調マーカー内のスペースエラー空白、強調
MD039no-space-in-linksリンク テキスト内のスペースエラー空白文字、リンク
MD040fenced-code-languageフェンスされたコード ブロックは言語を指定する必要がありますエラーコード、言語
MD042no-empty-links空のリンクなしエラーリンク
MD047single-trailing-newlineファイルは単一の改行文字で終わる必要がありますエラーblank_lines
MD049emphasis-style強調スタイルエラーemphasis
MD050strong-style強力なスタイルエラーemphasis
search-replacetodocs-placeholderTODOCS プレースホルダーの発生をキャッチします。エラー
search-replacedocs-domaindocs.gitub.com のドメインの発生をキャッチします。エラー
search-replacehelp-domainhelp.gitub.com のドメインの発生をキャッチします。エラー
search-replacepreview-domainpreview.ghdocs.com のドメインの発生をキャッチします。エラー
search-replacedeveloper-domaindeveloper.gitub.com のドメインの発生をキャッチします。エラー
search-replace非推奨の Liquid 構文: site.data非推奨の Liquid データ構文の発生をキャッチします。エラー
search-replace非推奨の liquid 構文: octicon-使用されている Octicon の Liquid 構文は非推奨です。 代わりにこの形式を使用してください octicon "<octicon-name>" aria-label="<Octicon aria label>"エラー
GH001no-default-alt-text画像には意味のある代替テキスト (alt text) が必要です。エラーアクセシビリティ、画像
GH002no-generic-link-textLearn moreClick here のような汎用リンク テキストを使用しないでくださいエラーアクセシビリティ、リンク
GHD030code-fence-line-lengthコード フェンス行が最大長を超えないようにしてくださいwarningコード、アクセシビリティ
GHD032image-alt-text-end-punctuation画像の代替テキストは、句読点で終わる必要がありますエラーアクセシビリティ、画像
GHD004image-file-kebab-caseイメージ ファイル名には kebab-case を使用する必要がありますエラーimages
GHD033incorrect-alt-text-length画像の代替テキストは 40 から 150 文字にする必要がありますwarningアクセシビリティ、画像
GHD002internal-links-no-lang内部リンクにハードコーディングされた言語コードを含めることはできませんエラーリンク、URL
GHD003internal-links-slash内部リンクは / で始まる必要がありますエラーリンク、URL
GHD031image-alt-text-exclude-words画像の代替テキストは、「image」や「graphic」などの単語で始めないでくださいエラーアクセシビリティ、画像
GHD034list-first-word-capitalizationリスト アイテムの最初の単語を大文字にする必要がありますwarningul、ol
GHD001link-punctuation内部リンク タイトルに句読点を含めてはならないエラーリンク、URL
GHD008early-access-references早期アクセスではないファイルは、早期アクセス ファイルまたは早期アクセス ファイルを参照しないでくださいエラー機能、早期アクセス
GHD021yaml-scheduled-jobsスケジュールされたワークフローを含む YAML スニペットは、正時に実行しないでください。また、一意である必要があります。エラー機能、アクション
GHD006internal-links-old-version内部リンクには、古いバージョン管理構文を使用してハードコーディングされたバージョンを含めてはなりませんエラーリンク、URL、バージョン管理
GHD005hardcoded-data-variable「個人用アクセス トークン」を含む文字列では、代わりに製品変数を使用する必要がありますエラーsingle-source
GHD013github-owned-action-referencesGitHub が所有する公式アクションへの参照をハードコーディングしないでくださいエラー機能、アクション
GHD016liquid-quoted-conditional-argLiquid の条件付きタグは、条件付き引数を引用符で囲まないでくださいエラーliquid、形式
GHD014liquid-data-references-definedLiquid データまたはインデントされたデータ参照が、値を持たないコンテンツまたはデータ ディレクトリに存在しないコンテンツで見つかりましたエラーliquid
GHD015liquid-data-tag-formatLiquid データまたはインデントされたデータ参照タグは、正しい形式である必要があり、正しい数の引数の番号と間隔が必要ですエラーliquid、形式
GHD010frontmatter-hidden-docsfrontmatter プロパティ hidden を持つアーティクルは、特定の製品にのみ配置できますエラーfrontmatter、機能、早期アクセス
GHD009frontmatter-early-access-references早期アクセスではないファイルは、早期アクセスを参照するフロントマッターを含めないでくださいエラーfrontmatter、機能、早期アクセス
GHD011frontmatter-video-transcriptsビデオの文字起こしを正しく構成する必要がありますエラーfrontmatter、機能、ビデオ文字起こし
GHD012frontmatter-schemaFrontmatter はスキーマに準拠している必要がありますエラーfrontmatter、スキーマ
GHD007code-annotationsMarkdown で定義されているコード注釈には、特定のレイアウト の frontmatter プロパティが含まれている必要がありますエラーコード、機能、注釈、frontmatter
GHD017frontmatter-liquid-syntaxFrontmatter プロパティでは、有効な Liquid を使用する必要がありますエラーliquid、frontmatter
GHD018liquid-syntaxMarkdown コンテンツに有効な Liquid を使用する必要がありますエラーliquid
GHD019liquid-if-tags引数が有効なバージョンの場合は、if タグの代わりに Liquid ifversion タグを使用する必要がありますエラーliquid、バージョン管理
GHD020liquid-ifversion-tagsLiquid ifversion タグには、有効なバージョン名を引数として含める必要がありますエラーliquid、バージョン管理
GHD022liquid-ifversion-versionsLiquid ifversion (および elsif) は常に true でない必要がありますwarningliquid、バージョン管理
GHD035rai-reusable-usageRAI の記事と再利用可能な項目は、data/reusables/rai ディレクトリ内の再利用可能なコンテンツのみを参照できますエラーfeature, rai
GHD036image-no-gif画像は GIF であってはなりません。スタイルガイド資料: reference: contributing/style-guide-and-content-model/style-guide.md#imagesエラーimages
GHD038expired-content期限切れのコンテンツは修復する必要があります。エラー期限切れ
GHD039expiring-soon間もなく期限切れになるコンテンツは、事前に対処する必要があります。warning期限切れ
GHD040table-liquid-versioningテーブルでは、適切な liquid バージョン管理形式を使用する必要がありますエラーtables
GHD041third-party-action-pinningサード パーティのアクションを使うコード例では、必ず完全な長さのコミット SHA にピン留めする必要があります。エラー機能、アクション

リンティング ルールの構文

一部のリンティング ルールでは、記事に追加できる HTML コメントに基づいて警告またはエラーが返されます。

期限切れ間近および期限切れのコンテンツの構文

有効期限日が手動で指定されたコンテンツのルール GHD038GHD039 チェック。 指定した日付の 14 日前に、コンテンツ リンターは、コンテンツが間もなく期限切れであることを示す警告を返します。 指定した日付以降、コンテンツ リンターはエラーを返し、コンテンツに修復のフラグを設定します。

コンテンツに有効期限日を追加するには、次の形式で有効期限日を含む HTML タグでラップします: <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

以下を使用してください。

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

期限切れのタグを HTML table要素に配置する場合は、セルだけでなく行全体をタグが囲むようにしてください。 次に例を示します。

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label is deprecated and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

リンター ルールの抑制

まれに、1 つまたは複数のリンター ルールに違反するものを文書化することが必要になる場合があります。 このような場合は、Markdown ファイルにコメントを追加することで、ルールを抑制できます。 すべてのルールまたは特定のルールを無効にすることができます。 制限するルールは常にできるだけ少なくしてください。 ファイル全体、Markdown ファイルのセクション、特定の行、または次の行のルールを無効にすることができます。

たとえば、逆リンク構文をチェックする正規表現 (^|/)[Cc]+odespace/ を含むアーティクルを作成する場合、逆リンクをチェックする MD011 ルールがトリガーされます。 次のコメントを追加することで、その特定の行でルール MD011 を無効にすることができます。

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

無視したい行がコード ブロック内にある場合は、次のコメントで囲むことで、コード ブロックを無視できます。

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

これらのコメントを使用して、ルールを有効または無効にすることができます。

コメント効果
<!-- markdownlint-disable -->すべてのルールを無効にする
<!-- markdownlint-enable -->すべてのルールを有効にする
<!-- markdownlint-disable-line -->現在の行のすべてのルールを無効にする
<!-- markdownlint-disable-next-line -->次の行のすべてのルールを無効にする
<!-- markdownlint-disable RULE-ONE RULE-TWO -->
<!-- markdownlint-enable RULE-ONE RULE-TWO -->名前ごとに 1 つまたは複数のルールを有効にする
<!-- markdownlint-disable-line RULE-NAME -->現在の行の名前ごとに 1 つまたは複数のルールを無効にする
<!-- markdownlint-disable-next-line RULE-NAME -->次の行の名前ごとに 1 つまたは複数のルールを無効にする