Merge pull request #42483 from github/repo-sync

Repo sync

Author: docs-bot

config/moda/secrets/production/secrets.yml

@@ -4,3 +4,5 @@ secrets:
     kind: latest_at_deployment_start
     key: COOKIE_SECRET
     type: salt
+    owner: '@github/docs-engineering'
+    externally_usable: true

config/moda/secrets/staging/secrets.yml

@@ -4,3 +4,5 @@ secrets:
     kind: latest_at_deployment_start
     key: COOKIE_SECRET
     type: salt
+    owner: '@github/docs-engineering'
+    externally_usable: true

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

@@ -64,6 +64,7 @@
 | GHD060 | journey-tracks-unique-ids | Journey track IDs must be unique within a page | error | frontmatter, journey-tracks, unique-ids |
 | GHD061 | frontmatter-hero-image | Hero image paths must be absolute, extensionless, and point to valid images in /assets/images/banner-images/ | error | frontmatter, images |
 | GHD062 | frontmatter-intro-links | introLinks keys must be valid keys defined in data/ui.yml under product_landing | error | frontmatter, single-source |
+| GHD063 | frontmatter-children | Children frontmatter paths must exist. Supports relative paths and absolute /content/ paths for cross-product inclusion. | error | frontmatter, children |
 | [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 |  |

src/content-linter/lib/linting-rules/frontmatter-children.ts

@@ -0,0 +1,100 @@
+import fs from 'fs'
+import path from 'path'
+import { addError } from 'markdownlint-rule-helpers'
+
+import { getFrontmatter } from '../helpers/utils'
+import type { RuleParams, RuleErrorCallback } from '@/content-linter/types'
+
+interface Frontmatter {
+  children?: string[]
+  [key: string]: unknown
+}
+
+/**
+ * Check if a child path is valid.
+ * Supports both:
+ * - Relative paths (e.g., /local-child) resolved from current directory
+ * - Absolute /content/ paths (e.g., /content/actions/workflows) resolved from content root
+ */
+function isValidChildPath(childPath: string, currentFilePath: string): boolean {
+  const ROOT = process.env.ROOT || '.'
+  const contentDir = path.resolve(ROOT, 'content')
+
+  let resolvedPath: string
+
+  if (childPath.startsWith('/content/')) {
+    // Absolute path from content root - strip /content/ prefix
+    const absoluteChildPath = childPath.slice('/content/'.length)
+    resolvedPath = path.resolve(contentDir, absoluteChildPath)
+  } else {
+    // Relative path from current file's directory
+    const currentDir: string = path.dirname(currentFilePath)
+    const normalizedPath = childPath.startsWith('/') ? childPath.substring(1) : childPath
+    resolvedPath = path.resolve(currentDir, normalizedPath)
+  }
+
+  // Security check: ensure resolved path stays within content directory
+  // This prevents path traversal attacks using sequences like '../'
+  if (!resolvedPath.startsWith(contentDir + path.sep) && resolvedPath !== contentDir) {
+    return false
+  }
+
+  // Check for direct .md file
+  const mdPath = `${resolvedPath}.md`
+  if (fs.existsSync(mdPath) && fs.statSync(mdPath).isFile()) {
+    return true
+  }
+
+  // Check for index.md file in directory
+  const indexPath = path.join(resolvedPath, 'index.md')
+  if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+    return true
+  }
+
+  // Check if the path exists as a directory (may have children)
+  if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isDirectory()) {
+    return true
+  }
+
+  return false
+}
+
+export const frontmatterChildren = {
+  names: ['GHD063', 'frontmatter-children'],
+  description:
+    'Children frontmatter paths must exist. Supports relative paths and absolute /content/ paths for cross-product inclusion.',
+  tags: ['frontmatter', 'children'],
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    const fm = getFrontmatter(params.lines) as Frontmatter | null
+    if (!fm || !fm.children) return
+
+    const childrenLine: string | undefined = params.lines.find((line) =>
+      line.startsWith('children:'),
+    )
+
+    if (!childrenLine) return
+
+    const lineNumber: number = params.lines.indexOf(childrenLine) + 1
+
+    if (Array.isArray(fm.children)) {
+      const invalidPaths: string[] = []
+
+      for (const child of fm.children) {
+        if (!isValidChildPath(child, params.name)) {
+          invalidPaths.push(child)
+        }
+      }
+
+      if (invalidPaths.length > 0) {
+        addError(
+          onError,
+          lineNumber,
+          `Found invalid children paths: ${invalidPaths.join(', ')}. For cross-product paths, use /content/ prefix (e.g., /content/actions/workflows).`,
+          childrenLine,
+          [1, childrenLine.length],
+          null,
+        )
+      }
+    }
+  },
+}

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

@@ -53,6 +53,7 @@ import { journeyTracksGuidePathExists } from './journey-tracks-guide-path-exists
 import { journeyTracksUniqueIds } from './journey-tracks-unique-ids'
 import { frontmatterHeroImage } from './frontmatter-hero-image'
 import { frontmatterIntroLinks } from './frontmatter-intro-links'
+import { frontmatterChildren } from './frontmatter-children'
 
 // Using any type because @github/markdownlint-github doesn't provide TypeScript declarations
 // The elements in the array have a 'names' property that contains rule identifiers
@@ -117,6 +118,7 @@ export const gitHubDocsMarkdownlint = {
     journeyTracksUniqueIds, // GHD060
     frontmatterHeroImage, // GHD061
     frontmatterIntroLinks, // GHD062
+    frontmatterChildren, // GHD063
 
     // Search-replace rules
     searchReplace, // Open-source plugin

src/content-linter/style/github-docs.ts

@@ -284,6 +284,12 @@ export const githubDocsFrontmatterConfig = {
     'partial-markdown-files': false,
     'yml-files': false,
   },
+  'frontmatter-children': {
+    // GHD063
+    severity: 'error',
+    'partial-markdown-files': false,
+    'yml-files': false,
+  },
 }
 
 // Configures rules from the `github/markdownlint-github` repo

src/content-linter/tests/category-pages.ts

@@ -239,6 +239,15 @@ describe.skip('category pages', () => {
 })
 
 function getPath(productDir: string, link: string, filename: string) {
+  // Handle absolute /content/ paths for cross-product children
+  // The link parameter contains the child path from frontmatter
+  if (link.startsWith('/content/')) {
+    const absolutePath = link.slice('/content/'.length)
+    if (filename === 'index') {
+      return path.join(contentDir, absolutePath, 'index.md')
+    }
+    return path.join(contentDir, absolutePath, `${filename}.md`)
+  }
   return path.join(productDir, link, `${filename}.md`)
 }
 

src/content-linter/tests/fixtures/frontmatter-children/invalid-paths.md

@@ -0,0 +1,8 @@
+---
+title: Invalid children paths
+children:
+  - /content/nonexistent/product
+  - /another/invalid/path
+---
+
+This page has invalid children paths.

src/content-linter/tests/fixtures/frontmatter-children/no-children.md

@@ -0,0 +1,5 @@
+---
+title: No children
+---
+
+This page has no children frontmatter.

src/content-linter/tests/fixtures/frontmatter-children/valid-content-prefix.md

@@ -0,0 +1,8 @@
+---
+title: Valid children with content prefix
+children:
+  - /content/get-started/foo
+  - /content/get-started/learning-about-github
+---
+
+This page has valid /content/ prefixed children paths.