Add note and warning formatting linter rule (#56120)

Author: heiskr

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

@@ -35,6 +35,7 @@ import { liquidTagWhitespace } from './liquid-tag-whitespace.js'
 import { linkQuotation } from './link-quotation.js'
 import { octiconAriaLabels } from './octicon-aria-labels.js'
 import { liquidIfversionVersions } from './liquid-ifversion-versions.js'
+import { noteWarningFormatting } from './note-warning-formatting.js'
 
 const noDefaultAltText = markdownlintGitHub.find((elem) =>
   elem.names.includes('no-default-alt-text'),
@@ -84,5 +85,6 @@ export const gitHubDocsMarkdownlint = {
     liquidTagWhitespace,
     linkQuotation,
     octiconAriaLabels,
+    noteWarningFormatting,
   ],
 }

src/content-linter/lib/linting-rules/note-warning-formatting.js

@@ -0,0 +1,220 @@
+import { addError } from 'markdownlint-rule-helpers'
+import { getRange } from '../helpers/utils.js'
+import frontmatter from '#src/frame/lib/read-frontmatter.js'
+
+export const noteWarningFormatting = {
+  names: ['GHD049', 'note-warning-formatting'],
+  description: 'Note and warning tags should be formatted according to style guide',
+  tags: ['formatting', 'callouts', 'notes', 'warnings', 'style'],
+  severity: 'warning',
+  function: (params, onError) => {
+    // Skip autogenerated files
+    const frontmatterString = params.frontMatterLines.join('\n')
+    const fm = frontmatter(frontmatterString).data
+    if (fm && fm.autogenerated) return
+
+    const lines = params.lines
+    let inLegacyNote = false
+    let noteStartLine = null
+    let noteContent = []
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const lineNumber = i + 1
+
+      // Check for legacy {% note %} tags
+      if (line.trim() === '{% note %}') {
+        inLegacyNote = true
+        noteStartLine = lineNumber
+        noteContent = []
+
+        // Check for missing line break before {% note %}
+        const prevLine = i > 0 ? lines[i - 1] : ''
+        if (prevLine.trim() !== '') {
+          const range = getRange(line, '{% note %}')
+          addError(onError, lineNumber, 'Add a blank line before {% note %} tag', line, range, {
+            editColumn: 1,
+            deleteCount: 0,
+            insertText: '\n',
+          })
+        }
+        continue
+      }
+
+      // Check for end of legacy note
+      if (line.trim() === '{% endnote %}') {
+        if (inLegacyNote) {
+          inLegacyNote = false
+
+          // Check for missing line break after {% endnote %}
+          const nextLine = i < lines.length - 1 ? lines[i + 1] : ''
+          if (nextLine.trim() !== '') {
+            const range = getRange(line, '{% endnote %}')
+            addError(onError, lineNumber, 'Add a blank line after {% endnote %} tag', line, range, {
+              editColumn: line.length + 1,
+              deleteCount: 0,
+              insertText: '\n',
+            })
+          }
+
+          // Check note content formatting
+          validateNoteContent(noteContent, noteStartLine, onError)
+        }
+        continue
+      }
+
+      // Collect content inside legacy notes
+      if (inLegacyNote) {
+        noteContent.push({ text: line, lineNumber: lineNumber })
+        continue
+      }
+
+      // Check for new-style callouts > [!NOTE], > [!WARNING], > [!DANGER]
+      const calloutMatch = line.match(/^>\s*\[!(NOTE|WARNING|DANGER)\]\s*$/)
+      if (calloutMatch) {
+        const calloutType = calloutMatch[1]
+
+        // Check for missing line break before callout
+        const prevLine = i > 0 ? lines[i - 1] : ''
+        if (prevLine.trim() !== '') {
+          const range = getRange(line, line.trim())
+          addError(
+            onError,
+            lineNumber,
+            `Add a blank line before > [!${calloutType}] callout`,
+            line,
+            range,
+            {
+              editColumn: 1,
+              deleteCount: 0,
+              insertText: '\n',
+            },
+          )
+        }
+
+        // Find the end of this callout block and validate content
+        const calloutContent = []
+        let j = i + 1
+        while (j < lines.length && lines[j].startsWith('>')) {
+          if (lines[j].trim() !== '>') {
+            calloutContent.push({ text: lines[j], lineNumber: j + 1 })
+          }
+          j++
+        }
+
+        // Check for missing line break after callout
+        if (j < lines.length && lines[j].trim() !== '') {
+          const range = getRange(lines[j], lines[j].trim())
+          addError(
+            onError,
+            j + 1,
+            `Add a blank line after > [!${calloutType}] callout block`,
+            lines[j],
+            range,
+            {
+              editColumn: 1,
+              deleteCount: 0,
+              insertText: '\n',
+            },
+          )
+        }
+
+        validateCalloutContent(calloutContent, calloutType, lineNumber, onError)
+        i = j - 1 // Skip to end of callout block
+        continue
+      }
+
+      // Check for orphaned **Note:**/**Warning:**/**Danger:** outside callouts
+      const orphanedPrefixMatch = line.match(/\*\*(Note|Warning|Danger):\*\*/)
+      if (orphanedPrefixMatch && !inLegacyNote && !line.startsWith('>')) {
+        const range = getRange(line, orphanedPrefixMatch[0])
+        addError(
+          onError,
+          lineNumber,
+          `${orphanedPrefixMatch[1]} prefix should be inside a callout block`,
+          line,
+          range,
+          null, // No auto-fix as this requires human decision
+        )
+      }
+    }
+  },
+}
+
+/**
+ * Validate content inside legacy {% note %} blocks
+ */
+function validateNoteContent(noteContent, noteStartLine, onError) {
+  if (noteContent.length === 0) return
+
+  const contentLines = noteContent.filter((item) => item.text.trim() !== '')
+  if (contentLines.length === 0) return
+
+  // Count bullet points
+  const bulletLines = contentLines.filter((item) => item.text.trim().match(/^[*\-+]\s/))
+  if (bulletLines.length > 2) {
+    const range = getRange(bulletLines[2].text, bulletLines[2].text.trim())
+    addError(
+      onError,
+      bulletLines[2].lineNumber,
+      'Do not include more than 2 bullet points inside a callout',
+      bulletLines[2].text,
+      range,
+      null, // No auto-fix as this requires content restructuring
+    )
+  }
+
+  // Check for missing prefix (only if it looks like a traditional note)
+  const firstContentLine = contentLines[0]
+  const allContent = contentLines.map((line) => line.text).join(' ')
+  const hasButtons =
+    allContent.includes('<a href=') || allContent.includes('btn') || allContent.includes('class=')
+
+  if (
+    !hasButtons &&
+    !firstContentLine.text.includes('**Note:**') &&
+    !firstContentLine.text.includes('**Warning:**') &&
+    !firstContentLine.text.includes('**Danger:**')
+  ) {
+    const range = getRange(firstContentLine.text, firstContentLine.text.trim())
+    addError(
+      onError,
+      firstContentLine.lineNumber,
+      'Note content should start with **Note:**, **Warning:**, or **Danger:**',
+      firstContentLine.text,
+      range,
+      {
+        editColumn: firstContentLine.text.indexOf(firstContentLine.text.trim()) + 1,
+        deleteCount: 0,
+        insertText: '**Note:** ',
+      },
+    )
+  }
+}
+
+/**
+ * Validate content inside new-style callouts
+ */
+function validateCalloutContent(calloutContent, calloutType, calloutStartLine, onError) {
+  if (calloutContent.length === 0) return
+
+  const contentLines = calloutContent.filter((item) => item.text.trim() !== '>')
+  if (contentLines.length === 0) return
+
+  // Count bullet points
+  const bulletLines = contentLines.filter((item) => item.text.match(/^>\s*[*\-+]\s/))
+  if (bulletLines.length > 2) {
+    const range = getRange(bulletLines[2].text, bulletLines[2].text.trim())
+    addError(
+      onError,
+      bulletLines[2].lineNumber,
+      'Do not include more than 2 bullet points inside a callout',
+      bulletLines[2].text,
+      range,
+      null, // No auto-fix as this requires content restructuring
+    )
+  }
+
+  // For new-style callouts, the prefix is handled by the [!NOTE] syntax itself
+  // so we don't need to check for manual **Note:** prefixes
+}