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

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 エラーが発生します。

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

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

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

npm run lint-content

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

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

npm run lint-content -- --errors

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

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

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

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 ブランチにマージされるのを妨げるものではありません。 コンテンツに警告違反がなくなると、ほとんどのルールは最終的にエラーに昇格します。

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

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

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

有効期限日が手動で指定されたコンテンツのルール GHD038 と GHD039 チェック。 指定した日付の 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 has been 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 -->

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