GitHub Docs コンテンツ リンターについて
コンテンツ リンターでは、Markdown コンテンツのスタイル ガイド ルールが適用されます。
リンターでは、markdownlint をフレームワークとして使ってチェックを実行し、欠陥を報告し、可能な場合はコンテンツを自動的に修正します。 このフレームワークは、柔軟に特定のルールを実行し、わかりやすいエラー メッセージを提供し、エラーを修正することができます。 GitHub Docs コンテンツ リンターは、いくつかの既存の markdownlint ルールと追加のカスタム ルールを使って、content ディレクトリと data ディレクトリ内の Markdown コンテンツをチェックします。 カスタム ルールでは、markdownlint フレームワークでまだ使用できないチェックか、GitHub Docs コンテンツに固有のチェックを実装します。 ルールによって、Markdown と Liquid の両方の構文がチェックされます。
GitHub Docs コンテンツ リンターの実行
GitHub Docs コンテンツ リンターは、事前コミット時に自動的に実行されますが、手動で実行することもできます。
事前コミット時にリンターを自動的に実行する
ローカルでコンテンツを記述し、コマンド ラインを使ってファイルをコミットすると、それらのステージングされたファイルはコンテンツ リンターによって自動的にリンティングされます。 警告とエラーの両方が報告されますが、コミットの完了を妨げるのはエラーのみです。
エラーが報告された場合、コミットは完了しません。 報告されたエラーを修正し、変更したファイルを再追加して、変更を再度コミットする必要があります。 報告されたエラーはすべて修正して、GitHub Docs スタイル ガイドに違反するエラーがコンテンツに含まれないようにする必要があります。 警告が報告された場合は、必要に応じて修正するかどうかを選択できます。
コンテンツをローカルで記述する場合、コマンド ラインで自動的に修正できるルールがいくつかあります。 修正できるエラーを自動的に修正する場合は、「修正できるエラーを自動的に修正する」をご覧ください。
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 ブランチにマージされるのを妨げるものではありません。 コンテンツに警告違反がなくなると、ほとんどのルールは最終的にエラーに昇格します。
| ルール ID | ルール名 | 説明 | Severity | タグ |
|---|
[MD001](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md) | heading-increment | 見出しレベルは、一度に 1 レベルだけ増分する必要があります | エラー | headings |
|
MD011 | no-reversed-links | 逆リンク構文 | エラー | リンク |
|
MD014 | commands-show-output | 出力を表示しないコマンドの前に使用するドル記号 | エラー | コード |
|
MD018 | no-missing-space-atx | atx スタイルの見出しでハッシュの後にスペースがありません | エラー | headings,atx, spaces |
|
MD019 | no-multiple-space-atx | atx スタイルの見出しでハッシュの後に複数のスペースがあります | エラー | headings,atx, spaces |
|
MD023 | heading-start-left | 見出しは行の先頭から始まる必要があります | エラー | 見出し、スペース |
|
MD027 | no-multiple-space-blockquote | ブロック引用記号の後に複数のスペースがあります | エラー | blockquote、空白、インデント |
|
MD029 | ol-prefix | 順序指定済みリスト アイテムのプレフィックス | エラー | ol |
|
MD030 | list-marker-space | リスト マーカーの後のスペース | エラー | ol、ul、空白 |
|
MD031 | blanks-around-fences | フェンスされたコード ブロックは空白行で囲む必要があります。 | エラー | コード、blank_lines |
|
MD037 | no-space-in-emphasis | 強調マーカー内のスペース | エラー | 空白、強調 |
|
MD039 | no-space-in-links | リンク テキスト内のスペース | エラー | 空白文字、リンク |
|
MD040 | fenced-code-language | フェンスされたコード ブロックは言語を指定する必要があります | エラー | コード、言語 |
|
MD042 | no-empty-links | 空のリンクなし | エラー | リンク |
|
MD050 | strong-style | 強力なスタイル | エラー | emphasis |
|
GH001 | no-default-alt-text | 画像には意味のある代替テキスト (alt text) が必要です。 | エラー | アクセシビリティ、画像 |
|
GH002 | no-generic-link-text |
Learn more や Click here のような汎用リンク テキストを使用しないでください | エラー | アクセシビリティ、リンク |
| GHD001 | link-punctuation | 内部リンク タイトルに句読点を含めてはならない | エラー | リンク、URL |
| GHD002 | internal-links-no-lang | 内部リンクにハードコーディングされた言語コードを含めることはできません | エラー | リンク、URL |
| GHD003 | internal-links-slash | 内部リンクは / で始まる必要があります | エラー | リンク、URL |
| GHD004 | image-file-kebab-case | イメージ ファイル名には kebab-case を使用する必要があります | エラー | 画像 |
| GHD005 | hardcoded-data-variable | 「個人用アクセス トークン」を含む文字列では、代わりに製品変数を使用する必要があります | エラー | single-source |
| GHD006 | internal-links-old-version | 内部リンクには、古いバージョン管理構文を使用してハードコーディングされたバージョンを含めてはなりません | エラー | リンク、URL、バージョン管理 |
| GHD007 | code-annotations | Markdown で定義されているコード注釈には、特定のレイアウト の frontmatter プロパティが含まれている必要があります | エラー | コード、機能、注釈、frontmatter |
| GHD008 | early-access-references | 早期アクセスではないファイルは、早期アクセス ファイルまたは早期アクセス ファイルを参照しないでください | エラー | 機能、早期アクセス |
| GHD009 | frontmatter-early-access-references | 早期アクセスではないファイルは、早期アクセスを参照するフロントマッターを含めないでください | エラー | frontmatter、機能、早期アクセス |
| GHD010 | frontmatter-hidden-docs | frontmatter プロパティ hidden を持つアーティクルは、特定の製品にのみ配置できます | エラー | frontmatter、機能、早期アクセス |
| GHD011 | frontmatter-video-transcripts | ビデオの文字起こしを正しく構成する必要があります | エラー | frontmatter、機能、ビデオ文字起こし |
| GHD012 | frontmatter-schema | Frontmatter はスキーマに準拠している必要があります | エラー | frontmatter、スキーマ |
| GHD013 | github-owned-action-references | GitHub が所有する公式アクションへの参照をハードコーディングしないでください | エラー | 機能、アクション |
| GHD014 | liquid-data-references-defined | Liquid データまたはインデントされたデータ参照が、値を持たないコンテンツまたはデータ ディレクトリに存在しないコンテンツで見つかりました | エラー | liquid |
| GHD015 | liquid-data-tag-format | Liquid データまたはインデントされたデータ参照タグは、正しい形式である必要があり、正しい数の引数の番号と間隔が必要です | エラー | liquid、形式 |
| GHD016 | liquid-quoted-conditional-arg | Liquid の条件付きタグは、条件付き引数を引用符で囲まないでください | エラー | liquid、形式 |
| GHD017 | frontmatter-liquid-syntax | Frontmatter プロパティでは、有効な Liquid を使用する必要があります | エラー | liquid、frontmatter |
| GHD018 | liquid-syntax | Markdown コンテンツに有効な Liquid を使用する必要があります | エラー | liquid |
| GHD019 | liquid-if-tags | 引数が有効なバージョンの場合は、ifversion タグの代わりに Liquid if タグを使用する必要があります | エラー | liquid、バージョン管理 |
| GHD020 | liquid-ifversion-tags | Liquid ifversion タグには、有効なバージョン名を引数として含める必要があります | エラー | liquid、バージョン管理 |
| GHD021 | yaml-scheduled-jobs | スケジュールされたワークフローを含む YAML スニペットは、正時に実行しないでください。また、一意である必要があります。 | エラー | 機能、アクション |
| GHD022 | liquid-ifversion-versions | Liquid の ifversion、elsif、else タグが有効である必要があり、サポートされていないバージョンが含まれていてはなりません。 | エラー | liquid、バージョン管理 |
| GHD031 | image-alt-text-exclude-words | 画像の代替テキストは、「image」や「graphic」などの単語で始めないでください | エラー | アクセシビリティ、画像 |
| GHD032 | image-alt-text-end-punctuation | 画像の代替テキストは、句読点で終わる必要があります | エラー | アクセシビリティ、画像 |
| GHD033 | incorrect-alt-text-length | 画像の代替テキストは 40 から 150 文字にする必要があります | エラー | アクセシビリティ、画像 |
| GHD035 | rai-reusable-usage | RAI の記事と再利用可能な項目は、data/reusables/rai ディレクトリ内の再利用可能なコンテンツのみを参照できます | エラー | 機能, レイ |
| GHD036 | image-no-gif | 画像は GIF であってはなりません。スタイルガイド資料: reference: contributing/style-guide-and-content-model/style-guide.md#images | エラー | 画像 |
| GHD038 | expired-content | 期限切れのコンテンツは修復する必要があります。 | 警告 | 期限切れ |
| GHD039 | expiring-soon | 間もなく期限切れになるコンテンツは、事前に対処する必要があります。 | 警告 | 期限切れ |
| GHD040 | table-liquid-versioning | テーブルでは、適切な liquid バージョン管理形式を使用する必要があります | エラー | tables |
| GHD041 | third-party-action-pinning | サード パーティのアクションを使うコード例では、必ず完全な長さのコミット SHA にピン留めする必要があります。 | エラー | 機能、アクション |
| GHD042 | liquid-tag-whitespace | Liquid タグは、1 つの空白で開始および終了する必要があります。 Liquid タグ引数は、1 つの空白のみで区切る必要があります。 | エラー | liquid、形式 |
| GHD043 | link-quotation | 内部リンクのタイトルは引用符で囲まないでください | エラー | リンク、URL |
| GHD045 | code-annotation-comment-spacing | 注釈ブロック内のコード コメントのコメント文字の後には、スペースが厳密に 1 つだけ含まれる必要があります | エラー | code、comments、annotate、spacing |
| GHD046 | outdated-release-phase-terminology | 古くなったリリース フェーズの用語は、現在の GitHub の用語に置き換える必要があります | エラー | terminology、consistency、release-phases |
| GHD047 | table-column-integrity | テーブルのすべての行で列数が一致している必要があります | エラー | tables、accessibility、formatting |
| GHD051 | frontmatter-versions-whitespace | バージョンのフロントマターに不要な空白が含まれていてはなりません | エラー | frontmatter、versions |
| GHD054 | third-party-actions-reusable | サード パーティのアクションを含むコード例には、再利用可能な免責事項が含まれる必要があります | エラー | actions、reusable、third-party |
| GHD056 | frontmatter-landing-recommended | 推奨される記事はランディング ページにのみ存在でき、推奨される記事が重複していてはならず、すべての推奨される記事が存在する必要があります | エラー | frontmatter、landing、recommended |
| GHD057 | ctas-schema | CTA URL はスキーマに準拠している必要があります | エラー | ctas、スキーマ、URL |
| GHD058 | ジャーニー・トラック・液体 | ジャーニートラックのプロパティでは、有効なLiquid 構文を使用する必要があります。 | エラー | frontmatter, ジャーニートラック, 液体 |
| GHD059 | 旅-軌跡-ガイド-パス-存在 | 体験トラックのガイドパスは、既存のコンテンツファイルを参照する必要があります | エラー | フロントマター、ジャーニートラックス |
| GHD060 | 旅程トラック固有ID | 体験トラック ID は、ページ内で一意である必要があります | エラー | frontmatter、journey-track、unique-ids |
| GHD061 | frontmatter-hero-image | ヒーロー イメージ のパスは絶対パスで、/assets/images/banner-images/ 内の有効なイメージを指す必要があります。 | エラー | フロントマター, 画像 |
| GHD062 | フロントマターイントロリンク | introLinks キーは、product_landingのデータ/ui.ymlで定義されている有効なキーである必要があります | エラー | frontmatter、単一ソース |
|
search-replace | 非推奨の liquid 構文: octicon-octicon "<octicon-name>" aria-label="<Octicon aria label>" | エラー | |
|
search-replace | 非推奨の Liquid 構文: site.data | 非推奨の Liquid データ構文の発生をキャッチします。 | エラー | |
|
search-replace | developer-domain | developer.gitub.com のドメインの発生をキャッチします。 | エラー | |
|
search-replace | docs-domain | docs.gitub.com のドメインの発生をキャッチします。 | エラー | |
|
search-replace | help-domain | help.gitub.com のドメインの発生をキャッチします。 | エラー | |
|
search-replace | todocs-placeholder | TODOCS プレースホルダーの発生をキャッチします。 | エラー | |
リンティング ルールの構文
一部のリンティング ルールでは、記事に追加できる 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 is 終了 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 つまたは複数のルールを無効にする |