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
ブランチにマージされるのを妨げるものではありません。 コンテンツに警告違反がなくなると、ほとんどのルールは最終的にエラーに昇格します。
ルール ID | ルール名 | 説明 | Severity | タグ |
---|---|---|---|---|
MD001 | heading-increment | 見出しレベルは、一度に 1 レベルだけ増分する必要があります | エラー | headings |
MD004 | ul-style | 順不同のリストスタイル | エラー | bullet、ul |
MD009 | no-trailing-spaces | 末尾のスペース | エラー | whitespace |
MD011 | no-reversed-links | 逆リンク構文 | エラー | リンク |
MD012 | no-multiple-blanks | 連続する複数の空白行 | エラー | 空白文字、blank_lines |
MD014 | commands-show-output | 出力を表示しないコマンドの前に使用するドル記号 | エラー | code |
MD018 | no-missing-space-atx | atx スタイルの見出しでハッシュの後にスペースがありません | エラー | headings,atx, spaces |
MD019 | no-multiple-space-atx | atx スタイルの見出しでハッシュの後に複数のスペースがあります | エラー | headings,atx, spaces |
MD022 | blanks-around-headings | 見出しは空白行で囲む必要があります | エラー | headings, blank_lines |
MD023 | heading-start-left | 見出しは行の先頭から始まる必要があります | エラー | headings, spaces |
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 | 空のリンクなし | エラー | リンク |
MD047 | single-trailing-newline | ファイルは単一の改行文字で終わる必要があります | エラー | blank_lines |
MD049 | emphasis-style | 強調スタイル | エラー | emphasis |
MD050 | strong-style | 強力なスタイル | エラー | emphasis |
search-replace | todocs-placeholder | TODOCS プレースホルダーの発生をキャッチします。 | エラー | |
search-replace | docs-domain | docs.gitub.com のドメインの発生をキャッチします。 | エラー | |
search-replace | help-domain | help.gitub.com のドメインの発生をキャッチします。 | エラー | |
search-replace | preview-domain | preview.ghdocs.com のドメインの発生をキャッチします。 | エラー | |
search-replace | developer-domain | developer.gitub.com のドメインの発生をキャッチします。 | エラー | |
search-replace | 非推奨の Liquid 構文: site.data | 非推奨の Liquid データ構文の発生をキャッチします。 | エラー | |
search-replace | 非推奨の liquid 構文: octicon- | 使用されている Octicon の Liquid 構文は非推奨です。 代わりにこの形式を使用してください octicon "<octicon-name>" aria-label="<Octicon aria label>" | エラー | |
GH001 | no-default-alt-text | 画像には意味のある代替テキスト (alt text) が必要です。 | エラー | アクセシビリティ、画像 |
GH002 | no-generic-link-text | Learn more や Click here のような汎用リンク テキストを使用しないでください | エラー | アクセシビリティ、リンク |
GHD030 | code-fence-line-length | コード フェンス行が最大長を超えないようにしてください | warning | コード、アクセシビリティ |
GHD032 | image-alt-text-end-punctuation | 画像の代替テキストは、句読点で終わる必要があります | エラー | アクセシビリティ、画像 |
GHD004 | image-file-kebab-case | イメージ ファイル名には kebab-case を使用する必要があります | エラー | images |
GHD033 | incorrect-alt-text-length | 画像の代替テキストは 40 から 150 文字にする必要があります | warning | アクセシビリティ、画像 |
GHD002 | internal-links-no-lang | 内部リンクにハードコーディングされた言語コードを含めることはできません | エラー | リンク、URL |
GHD003 | internal-links-slash | 内部リンクは / で始まる必要があります | エラー | リンク、URL |
GHD031 | image-alt-text-exclude-words | 画像の代替テキストは、「image」や「graphic」などの単語で始めないでください | エラー | アクセシビリティ、画像 |
GHD034 | list-first-word-capitalization | リスト アイテムの最初の単語を大文字にする必要があります | warning | ul、ol |
GHD001 | link-punctuation | 内部リンク タイトルに句読点を含めてはならない | エラー | リンク、URL |
GHD008 | early-access-references | 早期アクセスではないファイルは、早期アクセス ファイルまたは早期アクセス ファイルを参照しないでください | エラー | 機能、早期アクセス |
GHD021 | yaml-scheduled-jobs | スケジュールされたワークフローを含む YAML スニペットは、正時に実行しないでください。また、一意である必要があります。 | エラー | 機能、アクション |
GHD006 | internal-links-old-version | 内部リンクには、古いバージョン管理構文を使用してハードコーディングされたバージョンを含めてはなりません | エラー | リンク、URL、バージョン管理 |
GHD005 | hardcoded-data-variable | 「個人用アクセス トークン」を含む文字列では、代わりに製品変数を使用する必要があります | エラー | single-source |
GHD013 | github-owned-action-references | GitHub が所有する公式アクションへの参照をハードコーディングしないでください | エラー | 機能、アクション |
GHD016 | liquid-quoted-conditional-arg | Liquid の条件付きタグは、条件付き引数を引用符で囲まないでください | エラー | liquid、形式 |
GHD014 | liquid-data-references-defined | Liquid データまたはインデントされたデータ参照が、値を持たないコンテンツまたはデータ ディレクトリに存在しないコンテンツで見つかりました | エラー | liquid |
GHD015 | liquid-data-tag-format | Liquid データまたはインデントされたデータ参照タグは、正しい形式である必要があり、正しい数の引数の番号と間隔が必要です | エラー | liquid、形式 |
GHD010 | frontmatter-hidden-docs | frontmatter プロパティ hidden を持つアーティクルは、特定の製品にのみ配置できます | エラー | frontmatter、機能、早期アクセス |
GHD009 | frontmatter-early-access-references | 早期アクセスではないファイルは、早期アクセスを参照するフロントマッターを含めないでください | エラー | frontmatter、機能、早期アクセス |
GHD011 | frontmatter-video-transcripts | ビデオの文字起こしを正しく構成する必要があります | エラー | frontmatter、機能、ビデオ文字起こし |
GHD012 | frontmatter-schema | Frontmatter はスキーマに準拠している必要があります | エラー | frontmatter、スキーマ |
GHD007 | code-annotations | Markdown で定義されているコード注釈には、特定のレイアウト の frontmatter プロパティが含まれている必要があります | エラー | コード、機能、注釈、frontmatter |
GHD017 | frontmatter-liquid-syntax | Frontmatter プロパティでは、有効な Liquid を使用する必要があります | エラー | liquid、frontmatter |
GHD018 | liquid-syntax | Markdown コンテンツに有効な Liquid を使用する必要があります | エラー | liquid |
GHD019 | liquid-if-tags | 引数が有効なバージョンの場合は、if タグの代わりに Liquid ifversion タグを使用する必要があります | エラー | liquid、バージョン管理 |
GHD020 | liquid-ifversion-tags | Liquid ifversion タグには、有効なバージョン名を引数として含める必要があります | エラー | liquid、バージョン管理 |
GHD022 | liquid-ifversion-versions | Liquid ifversion (および elsif ) は常に true でない必要があります | warning | liquid、バージョン管理 |
GHD035 | rai-reusable-usage | RAI の記事と再利用可能な項目は、data/reusables/rai ディレクトリ内の再利用可能なコンテンツのみを参照できます | エラー | feature, rai |
GHD036 | image-no-gif | 画像は GIF であってはなりません。スタイルガイド資料: reference: contributing/style-guide-and-content-model/style-guide.md#images | エラー | images |
GHD038 | expired-content | 期限切れのコンテンツは修復する必要があります。 | エラー | 期限切れ |
GHD039 | expiring-soon | 間もなく期限切れになるコンテンツは、事前に対処する必要があります。 | warning | 期限切れ |
GHD040 | table-liquid-versioning | テーブルでは、適切な liquid バージョン管理形式を使用する必要があります | エラー | tables |
GHD041 | third-party-action-pinning | サード パーティのアクションを使うコード例では、必ず完全な長さのコミット SHA にピン留めする必要があります。 | エラー | 機能、アクション |
リンティング ルールの構文
一部のリンティング ルールでは、記事に追加できる 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 つまたは複数のルールを無効にする |