Add frontmatter validation linter rule (GHD055) (#56150)

heiskr · web-flow · commit cdecbb4a8fed · 2025-07-18T14:33:37.000Z
diff --git a/data/reusables/contributing/content-linter-rules.md b/data/reusables/contributing/content-linter-rules.md
@@ -70,6 +70,7 @@
 | 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 |
+| GHD055 | frontmatter-validation | Frontmatter properties must meet character limits and required property requirements | warning | frontmatter, character-limits, required-properties |
 | [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 |  |
 | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Catch occurrences of developer.github.com domain. | error |  |
diff --git a/src/content-linter/lib/linting-rules/frontmatter-validation.js b/src/content-linter/lib/linting-rules/frontmatter-validation.js
@@ -0,0 +1,165 @@
+import { addError } from 'markdownlint-rule-helpers'
+import { getFrontmatter } from '@/content-linter/lib/helpers/utils'
+
+export const frontmatterValidation = {
+  names: ['GHD055', 'frontmatter-validation'],
+  description:
+    'Frontmatter properties must meet character limits and required property requirements',
+  tags: ['frontmatter', 'character-limits', 'required-properties'],
+  function: (params, onError) => {
+    const fm = getFrontmatter(params.lines)
+    if (!fm) return
+
+    // Detect content type based on frontmatter properties and file path
+    const contentType = detectContentType(fm, params.name)
+
+    // Define character limits and requirements for different content types
+    const contentRules = {
+      category: {
+        title: { max: 70, recommended: 67 },
+        shortTitle: { max: 30, recommended: 27 },
+        intro: { required: true, recommended: 280, max: 362 },
+        requiredProperties: ['intro'],
+      },
+      mapTopic: {
+        title: { max: 70, recommended: 63 },
+        shortTitle: { max: 35, recommended: 30 },
+        intro: { required: true, recommended: 280, max: 362 },
+        requiredProperties: ['intro'],
+      },
+      article: {
+        title: { max: 80, recommended: 60 },
+        shortTitle: { max: 30, recommended: 25 },
+        intro: { required: false, recommended: 251, max: 354 },
+        requiredProperties: ['topics'],
+      },
+    }
+
+    const rules = contentRules[contentType]
+    if (!rules) return
+
+    // Check required properties
+    for (const property of rules.requiredProperties) {
+      if (!fm[property]) {
+        addError(
+          onError,
+          1,
+          `Missing required property '${property}' for ${contentType} content type`,
+          null,
+          null,
+          null,
+        )
+      }
+    }
+
+    // Check title length
+    if (fm.title) {
+      validatePropertyLength(onError, params.lines, 'title', fm.title, rules.title, 'Title')
+    }
+
+    // Check shortTitle length
+    if (fm.shortTitle) {
+      validatePropertyLength(
+        onError,
+        params.lines,
+        'shortTitle',
+        fm.shortTitle,
+        rules.shortTitle,
+        'ShortTitle',
+      )
+    }
+
+    // Check intro length if it exists
+    if (fm.intro && rules.intro) {
+      validatePropertyLength(onError, params.lines, 'intro', fm.intro, rules.intro, 'Intro')
+    }
+
+    // Cross-property validation: if title is longer than shortTitle limit, shortTitle must exist
+    if (fm.title && fm.title.length > rules.shortTitle.max && !fm.shortTitle) {
+      const titleLine = findPropertyLine(params.lines, 'title')
+      addError(
+        onError,
+        titleLine,
+        `Title is ${fm.title.length} characters, which exceeds the shortTitle limit of ${rules.shortTitle.max} characters. A shortTitle must be provided.`,
+        fm.title,
+        null,
+        null,
+      )
+    }
+
+    // Special validation for articles: should have at least one topic
+    if (contentType === 'article' && fm.topics) {
+      if (!Array.isArray(fm.topics)) {
+        const topicsLine = findPropertyLine(params.lines, 'topics')
+        addError(onError, topicsLine, 'Topics must be an array', String(fm.topics), null, null)
+      } else if (fm.topics.length === 0) {
+        const topicsLine = findPropertyLine(params.lines, 'topics')
+        addError(
+          onError,
+          topicsLine,
+          'Articles should have at least one topic',
+          'topics: []',
+          null,
+          null,
+        )
+      }
+    }
+  },
+}
+
+function validatePropertyLength(onError, lines, propertyName, propertyValue, limits, displayName) {
+  const propertyLength = propertyValue.length
+  const propertyLine = findPropertyLine(lines, propertyName)
+
+  // Only report the most severe error - maximum takes precedence over recommended
+  if (propertyLength > limits.max) {
+    addError(
+      onError,
+      propertyLine,
+      `${displayName} exceeds maximum length of ${limits.max} characters (current: ${propertyLength})`,
+      propertyValue,
+      null,
+      null,
+    )
+  } else if (propertyLength > limits.recommended) {
+    addError(
+      onError,
+      propertyLine,
+      `${displayName} exceeds recommended length of ${limits.recommended} characters (current: ${propertyLength})`,
+      propertyValue,
+      null,
+      null,
+    )
+  }
+}
+
+function detectContentType(frontmatter, filePath) {
+  // Only apply validation to markdown files
+  if (!filePath || !filePath.endsWith('.md')) {
+    return null
+  }
+
+  // Map topics have mapTopic: true
+  if (frontmatter.mapTopic === true) {
+    return 'mapTopic'
+  }
+
+  // Categories are index.md files that contain children but no mapTopic
+  // Only check files that look like they're in the content directory structure
+  if (
+    filePath.includes('/index.md') &&
+    frontmatter.children &&
+    Array.isArray(frontmatter.children) &&
+    !frontmatter.mapTopic
+  ) {
+    return 'category'
+  }
+
+  // Everything else is an article
+  return 'article'
+}
+
+function findPropertyLine(lines, property) {
+  const line = lines.find((line) => line.trim().startsWith(`${property}:`))
+  return line ? lines.indexOf(line) + 1 : 1
+}
diff --git a/src/content-linter/lib/linting-rules/index.js b/src/content-linter/lib/linting-rules/index.js
@@ -51,6 +51,7 @@ import { britishEnglishQuotes } from '@/content-linter/lib/linting-rules/british
 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 { frontmatterValidation } from '@/content-linter/lib/linting-rules/frontmatter-validation'
 import { headerContentRequirement } from '@/content-linter/lib/linting-rules/header-content-requirement'
 import { thirdPartyActionsReusable } from '@/content-linter/lib/linting-rules/third-party-actions-reusable'
 
@@ -113,6 +114,7 @@ export const gitHubDocsMarkdownlint = {
     frontmatterVersionsWhitespace, // GHD051
     headerContentRequirement, // GHD053
     thirdPartyActionsReusable, // GHD054
+    frontmatterValidation, // GHD055
 
     // Search-replace rules
     searchReplace, // Open-source plugin
diff --git a/src/content-linter/style/github-docs.js b/src/content-linter/style/github-docs.js
@@ -304,6 +304,12 @@ export const githubDocsFrontmatterConfig = {
     'partial-markdown-files': false,
     'yml-files': false,
   },
+  'frontmatter-validation': {
+    // GHD055
+    severity: 'warning',
+    'partial-markdown-files': false,
+    'yml-files': false,
+  },
 }
 
 // Configures rules from the `github/markdownlint-github` repo
diff --git a/src/content-linter/tests/unit/frontmatter-validation.js b/src/content-linter/tests/unit/frontmatter-validation.js
