From c0b82894d8be1ec991bc758b52ad556935d27e76 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Thu, 17 Jul 2025 12:07:41 -0700 Subject: [PATCH 1/2] Reorganize content linter rules with systematic four-section structure (#56564) --- .../contributing/content-linter-rules.md | 54 +++++----- src/content-linter/lib/linting-rules/index.js | 99 ++++++++++--------- .../linting-rules/table-liquid-versioning.js | 2 +- src/content-linter/scripts/generate-docs.ts | 43 +++++++- 4 files changed, 121 insertions(+), 77 deletions(-) diff --git a/data/reusables/contributing/content-linter-rules.md b/data/reusables/contributing/content-linter-rules.md index 126d0d424ade..03f499a02e8c 100644 --- a/data/reusables/contributing/content-linter-rules.md +++ b/data/reusables/contributing/content-linter-rules.md @@ -23,55 +23,55 @@ | [MD047](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md047.md) | single-trailing-newline | Files should end with a single newline character | error | blank_lines | | [MD049](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md049.md) | emphasis-style | Emphasis style | error | emphasis | | [MD050](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md050.md) | strong-style | Strong style | error | emphasis | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | todocs-placeholder | Catch occurrences of TODOCS placeholder. | error | | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | docs-domain | Catch occurrences of docs.github.com domain. | error | | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | help-domain | Catch occurrences of help.github.com domain. | error | | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Catch occurrences of developer.github.com domain. | error | | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: site.data | Catch occurrences of deprecated liquid data syntax. | error | | -| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: octicon- | The octicon liquid syntax used is deprecated. Use this format instead `octicon "" aria-label=""` | error | | | [GH001](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH001-no-default-alt-text.md) | no-default-alt-text | Images should have meaningful alternative text (alt text) | error | accessibility, images | | [GH002](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH002-no-generic-link-text.md) | no-generic-link-text | Avoid using generic link text like `Learn more` or `Click here` | error | accessibility, links | -| GHD030 | code-fence-line-length | Code fence lines should not exceed a maximum length | warning | code, accessibility | -| GHD032 | image-alt-text-end-punctuation | Alternate text for images should end with punctuation | error | accessibility, images | -| GHD004 | image-file-kebab-case | Image file names must use kebab-case | error | images | -| GHD033 | incorrect-alt-text-length | Images alternate text should be between 40-150 characters | warning | accessibility, images | +| GHD001 | link-punctuation | Internal link titles must not contain punctuation | error | links, url | | GHD002 | internal-links-no-lang | Internal links must not have a hardcoded language code | error | links, url | | GHD003 | internal-links-slash | Internal links must start with a / | error | links, url | -| GHD031 | image-alt-text-exclude-words | Alternate text for images should not begin with words like "image" or "graphic" | error | accessibility, images | -| GHD034 | list-first-word-capitalization | First word of list item should be capitalized | warning | ul, ol | -| GHD001 | link-punctuation | Internal link titles must not contain punctuation | error | links, url | -| GHD008 | early-access-references | Files that are not early access should not reference early-access or early-access files | error | feature, early-access | -| GHD021 | yaml-scheduled-jobs | YAML snippets that include scheduled workflows must not run on the hour and must be unique | error | feature, actions | -| GHD006 | internal-links-old-version | Internal links must not have a hardcoded version using old versioning syntax | error | links, url, versioning | +| GHD004 | image-file-kebab-case | Image file names must use kebab-case | error | images | | GHD005 | hardcoded-data-variable | Strings that contain "personal access token" should use the product variable instead | error | single-source | -| GHD013 | github-owned-action-references | GitHub-owned action references should not be hardcoded | error | feature, actions | -| GHD016 | liquid-quoted-conditional-arg | Liquid conditional tags should not quote the conditional argument | error | liquid, format | -| GHD014 | liquid-data-references-defined | Liquid data or indented data references were found in content that have no value or do not exist in the data directory | error | liquid | -| GHD015 | liquid-data-tag-format | Liquid data or indented data references tags must be correctly formatted and have the correct number of arguments and spacing | error | liquid, format | -| GHD010 | frontmatter-hidden-docs | Articles with frontmatter property `hidden` can only be located in specific products | error | frontmatter, feature, early-access | +| GHD006 | internal-links-old-version | Internal links must not have a hardcoded version using old versioning syntax | error | links, url, versioning | +| GHD007 | code-annotations | Code annotations defined in Markdown must contain a specific layout frontmatter property | error | code, feature, annotate, frontmatter | +| GHD008 | early-access-references | Files that are not early access should not reference early-access or early-access files | error | feature, early-access | | GHD009 | frontmatter-early-access-references | Files that are not early access should not have frontmatter that references early-access | error | frontmatter, feature, early-access | +| GHD010 | frontmatter-hidden-docs | Articles with frontmatter property `hidden` can only be located in specific products | error | frontmatter, feature, early-access | | GHD011 | frontmatter-video-transcripts | Video transcript must be configured correctly | error | frontmatter, feature, video-transcripts | | GHD012 | frontmatter-schema | Frontmatter must conform to the schema | error | frontmatter, schema | -| GHD007 | code-annotations | Code annotations defined in Markdown must contain a specific layout frontmatter property | error | code, feature, annotate, frontmatter | -| GHD045 | code-annotation-comment-spacing | Code comments in annotation blocks must have exactly one space after the comment character(s) | warning | code, comments, annotate, spacing | +| GHD013 | github-owned-action-references | GitHub-owned action references should not be hardcoded | error | feature, actions | +| GHD014 | liquid-data-references-defined | Liquid data or indented data references were found in content that have no value or do not exist in the data directory | error | liquid | +| GHD015 | liquid-data-tag-format | Liquid data or indented data references tags must be correctly formatted and have the correct number of arguments and spacing | error | liquid, format | +| GHD016 | liquid-quoted-conditional-arg | Liquid conditional tags should not quote the conditional argument | error | liquid, format | | GHD017 | frontmatter-liquid-syntax | Frontmatter properties must use valid Liquid | error | liquid, frontmatter | | GHD018 | liquid-syntax | Markdown content must use valid Liquid | error | liquid | | GHD019 | liquid-if-tags | Liquid `ifversion` tags should be used instead of `if` tags when the argument is a valid version | error | liquid, versioning | | GHD020 | liquid-ifversion-tags | Liquid `ifversion` tags should contain valid version names as arguments | error | liquid, versioning | +| GHD021 | yaml-scheduled-jobs | YAML snippets that include scheduled workflows must not run on the hour and must be unique | error | feature, actions | | GHD022 | liquid-ifversion-versions | Liquid `ifversion`, `elsif`, and `else` tags should be valid and not contain unsupported versions. | error | liquid, versioning | +| GHD030 | code-fence-line-length | Code fence lines should not exceed a maximum length | warning | code, accessibility | +| GHD031 | image-alt-text-exclude-words | Alternate text for images should not begin with words like "image" or "graphic" | error | accessibility, images | +| GHD032 | image-alt-text-end-punctuation | Alternate text for images should end with punctuation | error | accessibility, images | +| GHD033 | incorrect-alt-text-length | Images alternate text should be between 40-150 characters | warning | accessibility, images | +| GHD034 | list-first-word-capitalization | First word of list item should be capitalized | warning | ul, ol | | GHD035 | rai-reusable-usage | RAI articles and reusables can only reference reusable content in the data/reusables/rai directory | error | feature, rai | | GHD036 | image-no-gif | Image must not be a gif, styleguide reference: contributing/style-guide-and-content-model/style-guide.md#images | error | images | | GHD038 | expired-content | Expired content must be remediated. | warning | expired | | GHD039 | expiring-soon | Content that expires soon should be proactively addressed. | warning | expired | -| [GHD040](https://github.com/github/docs/blob/main/src/content-linter/README.md) | table-liquid-versioning | Tables must use the correct liquid versioning format | error | tables | -| GHD047 | table-column-integrity | Tables must have consistent column counts across all rows | warning | tables, accessibility, formatting | +| GHD040 | table-liquid-versioning | Tables must use the correct liquid versioning format | error | tables | | GHD041 | third-party-action-pinning | Code examples that use third-party actions must always pin to a full length commit SHA | error | feature, actions | | GHD042 | liquid-tag-whitespace | Liquid tags should start and end with one whitespace. Liquid tag arguments should be separated by only one whitespace. | error | liquid, format | | GHD043 | link-quotation | Internal link titles must not be surrounded by quotations | error | links, url | | GHD044 | octicon-aria-labels | Octicons should always have an aria-label attribute even if aria-hidden. | warning | accessibility, octicons | +| GHD045 | code-annotation-comment-spacing | Code comments in annotation blocks must have exactly one space after the comment character(s) | warning | code, comments, annotate, spacing | | GHD046 | outdated-release-phase-terminology | Outdated release phase terminology should be replaced with current GitHub terminology | warning | terminology, consistency, release-phases | +| GHD047 | table-column-integrity | Tables must have consistent column counts across all rows | warning | tables, accessibility, formatting | | GHD048 | british-english-quotes | Periods and commas should be placed inside quotation marks (American English style) | warning | punctuation, quotes, style, consistency | -| GHD050 | multiple-emphasis-patterns | Do not use more than one emphasis/strong, italics, or uppercase for a string | warning | formatting, emphasis, style | | GHD049 | note-warning-formatting | Note and warning tags should be formatted according to style guide | warning | formatting, callouts, notes, warnings, style | +| GHD050 | multiple-emphasis-patterns | Do not use more than one emphasis/strong, italics, or uppercase for a string | warning | formatting, emphasis, style | | GHD051 | frontmatter-versions-whitespace | Versions frontmatter should not contain unnecessary whitespace | warning | frontmatter, versions | -| GHD054 | third-party-actions-reusable | Code examples with third-party actions must include disclaimer reusable | warning | actions, reusable, third-party | \ No newline at end of file +| GHD054 | third-party-actions-reusable | Code examples with third-party actions must include disclaimer reusable | warning | actions, reusable, third-party | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: octicon- | The octicon liquid syntax used is deprecated. Use this format instead `octicon "" aria-label=""` | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: site.data | Catch occurrences of deprecated liquid data syntax. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Catch occurrences of developer.github.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | docs-domain | Catch occurrences of docs.github.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | help-domain | Catch occurrences of help.github.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | todocs-placeholder | Catch occurrences of TODOCS placeholder. | error | | \ No newline at end of file diff --git a/src/content-linter/lib/linting-rules/index.js b/src/content-linter/lib/linting-rules/index.js index 8afe18b8e7b6..aa8d5e557939 100644 --- a/src/content-linter/lib/linting-rules/index.js +++ b/src/content-linter/lib/linting-rules/index.js @@ -50,6 +50,7 @@ import { outdatedReleasePhaseTerminology } from '@/content-linter/lib/linting-ru import { britishEnglishQuotes } from '@/content-linter/lib/linting-rules/british-english-quotes' import { multipleEmphasisPatterns } from '@/content-linter/lib/linting-rules/multiple-emphasis-patterns' import { noteWarningFormatting } from '@/content-linter/lib/linting-rules/note-warning-formatting' + import { frontmatterVersionsWhitespace } from '@/content-linter/lib/linting-rules/frontmatter-versions-whitespace' import { thirdPartyActionsReusable } from '@/content-linter/lib/linting-rules/third-party-actions-reusable' @@ -62,52 +63,58 @@ const noGenericLinkText = markdownlintGitHub.find((elem) => export const gitHubDocsMarkdownlint = { rules: [ + // GH rules (markdownlint-github) + noDefaultAltText, // GH001 + noGenericLinkText, // GH002 + + // GHD rules (GitHub Docs custom rules, in numerical order) + linkPunctuation, // GHD001 + internalLinksNoLang, // GHD002 + internalLinksSlash, // GHD003 + imageFileKebabCase, // GHD004 + hardcodedDataVariable, // GHD005 + internalLinksOldVersion, // GHD006 + codeAnnotations, // GHD007 + earlyAccessReferences, // GHD008 + frontmatterEarlyAccessReferences, // GHD009 + frontmatterHiddenDocs, // GHD010 + frontmatterVideoTranscripts, // GHD011 + frontmatterSchema, // GHD012 + githubOwnedActionReferences, // GHD013 + liquidDataReferencesDefined, // GHD014 + liquidDataTagFormat, // GHD015 + liquidQuotedConditionalArg, // GHD016 + frontmatterLiquidSyntax, // GHD017 + liquidSyntax, // GHD018 + liquidIfTags, // GHD019 + liquidIfVersionTags, // GHD020 + yamlScheduledJobs, // GHD021 + liquidIfversionVersions, // GHD022 + codeFenceLineLength, // GHD030 + imageAltTextExcludeStartWords, // GHD031 + imageAltTextEndPunctuation, // GHD032 + incorrectAltTextLength, // GHD033 + listFirstWordCapitalization, // GHD034 + raiReusableUsage, // GHD035 + imageNoGif, // GHD036 + expiredContent, // GHD038 + expiringSoon, // GHD039 + tableLiquidVersioning, // GHD040 + thirdPartyActionPinning, // GHD041 + liquidTagWhitespace, // GHD042 + linkQuotation, // GHD043 + octiconAriaLabels, // GHD044 + codeAnnotationCommentSpacing, // GHD045 + outdatedReleasePhaseTerminology, // GHD046 + tableColumnIntegrity, // GHD047 + britishEnglishQuotes, // GHD048 + noteWarningFormatting, // GHD049 + multipleEmphasisPatterns, // GHD050 + frontmatterVersionsWhitespace, // GHD051 + + thirdPartyActionsReusable, // GHD054 + + // Search-replace rules searchReplace, // Open-source plugin - noDefaultAltText, // markdownlint-github rule - noGenericLinkText, // markdownlint-github rule - codeFenceLineLength, - imageAltTextEndPunctuation, - imageFileKebabCase, - incorrectAltTextLength, - internalLinksNoLang, - internalLinksSlash, - imageAltTextExcludeStartWords, - listFirstWordCapitalization, - linkPunctuation, - earlyAccessReferences, - yamlScheduledJobs, - internalLinksOldVersion, - hardcodedDataVariable, - githubOwnedActionReferences, - liquidQuotedConditionalArg, - liquidDataReferencesDefined, - liquidDataTagFormat, - frontmatterHiddenDocs, - frontmatterEarlyAccessReferences, - frontmatterVideoTranscripts, - frontmatterSchema, - codeAnnotations, - codeAnnotationCommentSpacing, - frontmatterLiquidSyntax, - liquidSyntax, - liquidIfTags, - liquidIfVersionTags, - liquidIfversionVersions, - raiReusableUsage, - imageNoGif, - expiredContent, - expiringSoon, - tableLiquidVersioning, - tableColumnIntegrity, - thirdPartyActionPinning, - liquidTagWhitespace, - linkQuotation, - octiconAriaLabels, - outdatedReleasePhaseTerminology, - britishEnglishQuotes, - multipleEmphasisPatterns, - noteWarningFormatting, - frontmatterVersionsWhitespace, - thirdPartyActionsReusable, ], } diff --git a/src/content-linter/lib/linting-rules/table-liquid-versioning.js b/src/content-linter/lib/linting-rules/table-liquid-versioning.js index fe32d02abcb6..e2dea1f4805f 100644 --- a/src/content-linter/lib/linting-rules/table-liquid-versioning.js +++ b/src/content-linter/lib/linting-rules/table-liquid-versioning.js @@ -14,7 +14,7 @@ export const tableLiquidVersioning = { description: 'Tables must use the correct liquid versioning format', severity: 'error', tags: ['tables'], - information: new URL('https://github.com/github/docs/blob/main/src/content-linter/README.md'), + function: function GHD040(params, onError) { const lines = params.lines let inTable = false diff --git a/src/content-linter/scripts/generate-docs.ts b/src/content-linter/scripts/generate-docs.ts index ca306bcae69b..be11c3378252 100644 --- a/src/content-linter/scripts/generate-docs.ts +++ b/src/content-linter/scripts/generate-docs.ts @@ -14,11 +14,17 @@ function main() { markdown.push('| Rule ID | Rule Name(s) | Description | Severity | Tags |') markdown.push('| ------- | ------------ | ----------- | -------- | ---- |') + // Collect all rules and their generated rows + const mdRules: Array<{ ruleId: string; row: string }> = [] + const ghRules: Array<{ ruleId: string; row: string }> = [] + const ghdRules: Array<{ ruleId: string; row: string }> = [] + const searchReplaceRows: string[] = [] + for (const rule of allRules as Rule[]) { const ruleName = rule.names.find((name) => name in allConfig) if (!ruleName) continue if (rule.names.includes('search-replace')) { - markdown.push(...getSearchReplaceRules(rule, allConfig[ruleName])) + searchReplaceRows.push(...getSearchReplaceRules(rule, allConfig[ruleName])) continue } const row = [] @@ -28,8 +34,35 @@ function main() { row.push(rule.description) row.push(allConfig[ruleName].severity) row.push(rule.tags.join(', ')) - markdown.push(`| ${row.join(' | ')} |`) + + // Categorize rules by their ID prefix + const ruleData = { ruleId: rule.names[0], row: `| ${row.join(' | ')} |` } + if (rule.names[0].startsWith('GHD')) { + ghdRules.push(ruleData) + } else if (rule.names[0].startsWith('GH')) { + ghRules.push(ruleData) + } else { + mdRules.push(ruleData) + } + } + + // Sort each category alphabetically by rule ID + mdRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId)) + ghRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId)) + ghdRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId)) + + // Add rules in order: MD rules, then GH rules, then GHD rules, then search-replace rules + for (const { row } of mdRules) { + markdown.push(row) + } + for (const { row } of ghRules) { + markdown.push(row) + } + for (const { row } of ghdRules) { + markdown.push(row) } + markdown.push(...searchReplaceRows) + writeFileSync('data/reusables/contributing/content-linter-rules.md', markdown.join('\n')) } @@ -38,7 +71,11 @@ function main() { function getSearchReplaceRules(srRule: Rule, ruleConfig: Config) { const name = srRule.information ? `[search-replace](${srRule.information})` : 'search-replace' const markdown = [] - for (const rule of ruleConfig.rules || []) { + + // Sort rules alphabetically by name + const sortedRules = [...(ruleConfig.rules || [])].sort((a, b) => a.name.localeCompare(b.name)) + + for (const rule of sortedRules) { const row = [] row.push(name) row.push(rule.name) From 10a257469c0add89c471ce0f9311a796ccf17822 Mon Sep 17 00:00:00 2001 From: Ricardo Kreyhsig <2385700+rickreyhsig@users.noreply.github.com> Date: Thu, 17 Jul 2025 17:07:58 -0400 Subject: [PATCH 2/2] Update list of registries for Dependabot configuration (#56703) --- .../configuring-access-to-private-registries-for-dependabot.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md b/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md index 4bb01dabc320..ddce43061e35 100644 --- a/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md +++ b/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md @@ -160,8 +160,7 @@ Examples of how to configure access to the private registries supported by {% da * [`cargo-registry`](#cargo-registry) * [`composer-repository`](#composer-repository) * [`docker-registry`](#docker-registry) -* [`git`](#git){% ifversion dependabot-helm-support %} -* [`helm-registry`](#helm-registry){% endif %} +* [`git`](#git) * [`hex-organization`](#hex-organization) * [`hex-repository`](#hex-repository) * [`maven-repository`](#maven-repository)