Merge pull request #39383 from github/repo-sync

Repo sync

Author: docs-bot

data/reusables/contributing/content-linter-rules.md

@@ -68,6 +68,7 @@
 | 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 |
+| GHD053 | header-content-requirement | Headers must have content between them, such as an introduction | warning | headers, structure, content |
 | 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-<icon-name> | The octicon liquid syntax used is deprecated. Use this format instead `octicon "<octicon-name>" aria-label="<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 |  |

package-lock.json

@@ -265,7 +265,7 @@
     "cheerio": "^1.0.0-rc.12",
     "cheerio-to-text": "0.2.4",
     "classnames": "^2.5.1",
-    "connect-timeout": "1.9.0",
+    "connect-timeout": "1.9.1",
     "cookie-parser": "^1.4.7",
     "cuss": "2.2.0",
     "dayjs": "^1.11.13",
@@ -304,7 +304,7 @@
     "mdast-util-to-hast": "^13.2.0",
     "mdast-util-to-markdown": "2.1.2",
     "mdast-util-to-string": "^4.0.0",
-    "morgan": "^1.10.0",
+    "morgan": "^1.10.1",
     "next": "^15.3.3",
     "ora": "^8.0.1",
     "parse5": "7.1.2",

package.json

@@ -0,0 +1,100 @@
+import { addError, filterTokens } from 'markdownlint-rule-helpers'
+
+export const headerContentRequirement = {
+  names: ['GHD053', 'header-content-requirement'],
+  description: 'Headers must have content between them, such as an introduction',
+  tags: ['headers', 'structure', 'content'],
+  function: (params, onError) => {
+    const headings = []
+
+    // Collect all heading tokens with their line numbers and levels
+    filterTokens(params, 'heading_open', (token) => {
+      headings.push({
+        token,
+        lineNumber: token.lineNumber,
+        level: parseInt(token.tag.slice(1)), // Extract number from h1, h2, etc.
+        line: params.lines[token.lineNumber - 1],
+      })
+    })
+
+    // Check each pair of consecutive headings
+    for (let i = 0; i < headings.length - 1; i++) {
+      const currentHeading = headings[i]
+      const nextHeading = headings[i + 1]
+
+      // Only check if next heading is a subheading (higher level number)
+      if (nextHeading.level > currentHeading.level) {
+        const hasContent = checkForContentBetweenHeadings(
+          params.lines,
+          currentHeading.lineNumber,
+          nextHeading.lineNumber,
+        )
+
+        if (!hasContent) {
+          addError(
+            onError,
+            nextHeading.lineNumber,
+            `Header must have introductory content before subheader. Add content between "${currentHeading.line.trim()}" and "${nextHeading.line.trim()}".`,
+            nextHeading.line,
+            null, // No specific range within the line
+            null, // No fix possible - requires manual content addition
+          )
+        }
+      }
+    }
+  },
+}
+
+/**
+ * Check if there is meaningful content between two headings
+ * Returns true if content exists, false if only whitespace/empty lines
+ */
+function checkForContentBetweenHeadings(lines, startLineNumber, endLineNumber) {
+  // Convert to 0-based indexes and skip the heading lines themselves
+  const startIndex = startLineNumber // Skip the current heading line
+  const endIndex = endLineNumber - 2 // Stop before the next heading line
+
+  // Check each line between the headings
+  for (let i = startIndex; i <= endIndex; i++) {
+    if (i >= lines.length) break
+
+    const line = lines[i].trim()
+
+    // Skip empty lines
+    if (line === '') continue
+
+    // Skip frontmatter delimiters
+    if (line === '---') continue
+
+    // Skip Liquid tags that don't produce visible content
+    if (isNonContentLiquidTag(line)) continue
+
+    // If we find any other content, consider it valid
+    if (line.length > 0) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a line contains only Liquid tags that don't produce visible content
+ * This helps avoid false positives for conditional blocks
+ */
+function isNonContentLiquidTag(line) {
+  // Match common non-content Liquid tags
+  const nonContentTags = [
+    /^{%\s*ifversion\s+.*%}$/,
+    /^{%\s*elsif\s+.*%}$/,
+    /^{%\s*else\s*%}$/,
+    /^{%\s*endif\s*%}$/,
+    /^{%\s*if\s+.*%}$/,
+    /^{%\s*unless\s+.*%}$/,
+    /^{%\s*endunless\s*%}$/,
+    /^{%\s*comment\s*%}$/,
+    /^{%\s*endcomment\s*%}$/,
+  ]
+
+  return nonContentTags.some((pattern) => pattern.test(line))
+}

src/content-linter/lib/linting-rules/header-content-requirement.js

@@ -50,8 +50,8 @@ 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 { headerContentRequirement } from '@/content-linter/lib/linting-rules/header-content-requirement'
 import { thirdPartyActionsReusable } from '@/content-linter/lib/linting-rules/third-party-actions-reusable'
 
 const noDefaultAltText = markdownlintGitHub.find((elem) =>
@@ -111,7 +111,7 @@ export const gitHubDocsMarkdownlint = {
     noteWarningFormatting, // GHD049
     multipleEmphasisPatterns, // GHD050
     frontmatterVersionsWhitespace, // GHD051
-
+    headerContentRequirement, // GHD053
     thirdPartyActionsReusable, // GHD054
 
     // Search-replace rules

src/content-linter/lib/linting-rules/index.js

@@ -237,6 +237,12 @@ const githubDocsConfig = {
     'partial-markdown-files': true,
     'yml-files': true,
   },
+  'header-content-requirement': {
+    // GHD053
+    severity: 'warning',
+    'partial-markdown-files': true,
+    'yml-files': true,
+  },
   'third-party-actions-reusable': {
     // GHD054
     severity: 'warning',