Disable remark-lint formatting enforcement for content files (GitHub Alerts incompatibility)

[jstirnaman]

Problem

Remark-stringify automatically escapes square brackets in markdown during formatting, converting GitHub Alerts syntax:

> [!Note]
> This is a note

to:

> \[!Note]
> This is a note

This breaks GitHub Alerts rendering, as the escaped version renders as literal text instead of styled alert boxes.

Root Cause

1. Remark-stringify behavior: By design, remark-stringify escapes square brackets that appear to be link references but have no corresponding definition
2. No GitHub Alerts support: The remark ecosystem doesn't have micromark/mdast extensions that properly handle GitHub Alerts syntax during markdown-to-markdown stringification
3. remark-gfm limitation: While remark-gfm supports many GitHub Flavored Markdown features (tables, task lists, strikethrough), it does NOT support GitHub Alerts
4. Available plugins are for HTML output: Plugins like remark-github-beta-blockquote-admonitions only transform markdown to HTML (rehype), not preserve markdown-to-markdown

Investigation Summary

We attempted several solutions:

1. ❌ Override remark-lint-no-undefined-references rule: Configured allow list for !Note, !Tip, etc. - this prevents lint warnings but doesn't stop stringify escaping
2. ❌ Add remark-github-beta-blockquote-admonitions plugin: Only handles markdown-to-HTML transformation
3. ❌ Create custom stringify handler: Remark doesn't provide API hooks to prevent escaping at this level
4. ❌ Use enkidevs/remark-stringify fork: Fork claims to support opt-out escaping but documentation is unclear

Solution Implemented

Disabled the lint-markdown-content pre-commit hook that was enforcing remark formatting on content files.

Rationale

1. ✅ Content files use GitHub Alerts extensively - escaping breaks functionality
2. ✅ Vale provides style linting - adequate coverage for content files
3. ✅ Instruction files still auto-fix - README, DOCS-*.md, .github/, .claude/ files still use remark formatting (these don't contain GitHub Alerts)
4. ✅ Hook was very new - added Oct 27, 2024 (just 4 days before this fix)
5. ✅ Simple and maintainable - doesn't require complex workarounds

Changes Made

1. lefthook.yml: Removed lint-markdown-content hook
2. .ci/remark-lint/.remark-lint.js: Kept remark-lint-no-undefined-references override with allow list for GitHub Alerts (prevents lint warnings)
3. .ci/remark-lint/package.json: Added remark-lint-no-undefined-references dependency

What Still Works

• ✅ Remark auto-fixes instruction files (README.md, DOCS-*.md, etc.)
• ✅ Vale style linting on all content files
• ✅ Vale linting on instruction files
• ✅ All other pre-commit hooks (Prettier, ESLint, etc.)
• ✅ GitHub Alerts render correctly in content files

What Changed

• ❌ No longer enforces remark formatting consistency on content files
• ℹ️ Content files rely on Vale for style enforcement instead

Commented-out Hook Code (for reference)

# NOTE: lint-markdown-content hook disabled because remark-stringify escapes
# square brackets in GitHub Alerts syntax (> [!Note] becomes > \[!Note]),
# which breaks alert rendering. Content files use GitHub Alerts extensively,
# and Vale provides sufficient style linting for content.
# See: https://github.com/remarkjs/remark-gfm/issues/53
#
# lint-markdown-content:
#   tags: lint
#   glob: "{api-docs/**/*.md,content/**/*.md}"
#   run: |
#     files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g')
#     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"
#         exit 1
#       fi
#     done
#     echo "✅ All content files are properly formatted"

Future Considerations

If the remark ecosystem adds proper GitHub Alerts support in the future:

1. Watch for updates to remark-gfm that add GitHub Alerts support
2. Monitor Support GitHub's note/warning/information alerts? remarkjs/remark-gfm#53 for progress
3. Consider re-enabling lint-markdown-content once proper support exists

References

• GitHub Alerts documentation
• remark-gfm GitHub Alerts issue
• remark-lint-no-undefined-references

[jstirnaman]

Issue resolved. The lint-markdown-content hook has been removed from lefthook.yml. Content files now preserve GitHub Alerts syntax correctly while instruction files continue to use remark formatting.