fix(lint): disable remark formatting for content files to preserve GitHub Alerts (#6502)

Remark-stringify escapes square brackets in GitHub Alerts syntax
(> [!Note] becomes > \[!Note]), breaking alert rendering.

Changes:
- Remove lint-markdown-content pre-commit hook from lefthook.yml
- Configure remark-lint-no-undefined-references to allow GitHub Alerts
- Add remark-lint-no-undefined-references dependency
- Unescaped GitHub Alerts in content/create.md

Content files now preserve GitHub Alerts syntax while instruction files
continue to use remark auto-formatting (they don't contain alerts).
Vale provides adequate style linting for content files.

Closes #6501
See: remarkjs/remark-gfm#53

Author: jstirnaman

.ci/remark-lint/.remark-lint.js

@@ -4,22 +4,31 @@ import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-styl
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkFrontmatterSchema from 'remark-lint-frontmatter-schema';
 import remarkNoShellDollars from 'remark-lint-no-shell-dollars';
+import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references';
 import remarkToc from 'remark-toc';
 
 const remarkConfig = {
   settings: {
     bullet: '-',
-    plugins: [
-      remarkPresetLintConsistent,
-      remarkPresetLintRecommended,
-      remarkPresetLintMarkdownStyleGuide,
-      remarkFrontmatter,
-      remarkFrontmatterSchema,
-      remarkNoShellDollars,
-      // Generate a table of contents in `## Contents`
-      [remarkToc, { heading: '' }],
-    ],
   },
+  plugins: [
+    remarkPresetLintConsistent,
+    remarkPresetLintRecommended,
+    remarkPresetLintMarkdownStyleGuide,
+    remarkFrontmatter,
+    remarkFrontmatterSchema,
+    remarkNoShellDollars,
+    // Override no-undefined-references to allow GitHub Alerts syntax
+    // This prevents lint warnings for [!Note], [!Tip], etc. in blockquotes
+    [
+      remarkLintNoUndefinedReferences,
+      {
+        allow: ['!Note', '!Tip', '!Important', '!Warning', '!Caution'],
+      },
+    ],
+    // Generate a table of contents in `## Contents`
+    [remarkToc, { heading: '' }],
+  ],
 };
 
 export default remarkConfig;

.ci/remark-lint/package.json

@@ -9,6 +9,7 @@
     "remark-preset-lint-recommended": "7.0.0",
     "remark-frontmatter": "5.0.0",
     "remark-lint-frontmatter-schema": "3.15.4",
-    "remark-lint-no-shell-dollars": "4.0.0"
+    "remark-lint-no-shell-dollars": "4.0.0",
+    "remark-lint-no-undefined-references": "5.0.2"
   }
 }

lefthook.yml

@@ -22,26 +22,6 @@ pre-commit:
         docker compose run --rm --name remark-lint remark-lint $files --output --quiet || \
           { echo "⚠️  Remark found formatting issues in instruction files. Automatic formatting applied."; }
       stage_fixed: true
-    # Report markdown formatting issues in content/api-docs without auto-fixing
-    lint-markdown-content:
-      tags: lint
-      glob: "{api-docs/**/*.md,content/**/*.md}"
-      run: |
-        # Prepend /workdir/ to staged files since repository is mounted at /workdir in container
-        files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g')
-        # Run remark to check for formatting differences (without --output, shows diff in stdout)
-        # If output differs from input, fail the commit
-        for file in $files; do
-          original=$(cat "${file#/workdir/}")
-          formatted=$(docker compose run --rm --name remark-lint-content remark-lint "$file" 2>/dev/null | tail -n +2)
-          if [ "$original" != "$formatted" ]; then
-            echo "❌ Markdown formatting issues in ${file#/workdir/}"
-            echo "   Run: docker compose run --rm remark-lint $file --output"
-            echo "   Or manually fix the formatting to match remark style"
-            exit 1
-          fi
-        done
-        echo "✅ All content files are properly formatted"
     # Lint instruction and repository documentation files with generic Vale config
     lint-instructions:
       tags: lint