[Feature]: Add support for GitHub-flavored markdown alerts

[FrankLedo]

Package

markdown-confluence-sync

Description

Add support for GitHub-flavored markdown alerts (also known as "note blocks" or "admonitions") to the markdown-confluence-sync tool. These alerts use the syntax [!NOTE], [!WARNING], [!TIP], [!IMPORTANT], and [!CAUTION] within blockquotes and are commonly used in GitHub documentation.

Background

GitHub introduced alert syntax in December 2023 as a way to highlight critical information in markdown files. The syntax looks like this:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

See GitHub's documentation:
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

Motivation

This repository's CONTRIBUTING.md file (lines 48-49, 59, 143, 166) already uses GitHub alerts syntax, but these alerts do not render properly when synced to Confluence. They appear as plain quoted blocks, losing their semantic meaning and visual distinction.

Supporting this feature would:

1. Improve documentation quality when syncing from GitHub to Confluence
2. Maintain consistency with modern markdown standards
3. Follow the same pattern as the recently implemented code blocks feature (Bug: Code Blocks Rendering as Inline Code in Confluence #65)
4. Enable better visual hierarchy in Confluence pages

Suggested Solution

Implement a new rehype plugin (rehype-replace-alerts.ts) that transforms GitHub alert syntax to Confluence's native info/note/warning/tip macros. The implementation would follow the same architecture pattern as the recently added code blocks feature.

Mapping

GitHub Alert	Confluence Macro
[!NOTE]	info macro
[!TIP]	tip macro
[!IMPORTANT]	note macro
[!WARNING]	warning macro
[!CAUTION]	warning macro

Configuration

Similar to the code blocks feature, this would be an opt-in feature controlled by a configuration option:

// markdown-confluence-sync.config.cjs
module.exports = {
  rehype: {
    alerts: true  // Enable GitHub alerts transformation
  }
}

Default: false (disabled for backward compatibility)

Implementation Notes

The implementation would include:

• New rehype plugin: rehype-replace-alerts.ts
• Configuration option in ConfluenceSync.ts
• Type definitions in ConfluenceSync.types.ts
• Integration in ConfluencePageTransformer.ts
• Comprehensive unit tests
• Documentation updates in README.md

Related Work

• Bug: Code Blocks Rendering as Inline Code in Confluence #65 - Code blocks transformation (provides architectural pattern to follow)
• Similar to how rehype-replace-details.ts handles <details> elements

Contributor

I am happy to implement this feature and submit a pull request.

Acceptance Criteria

• GitHub alert syntax is detected and transformed to Confluence macros
• All five alert types are supported
• Feature is opt-in via rehype.alerts configuration option
• Comprehensive unit tests cover all alert types and edge cases
• Documentation is updated in README.md
• CHANGELOG.md is updated
• Package version is bumped appropriately
• All existing tests pass
• Linter passes without errors

Code of Conduct

• I agree to follow this project's Code of Conduct

[javierbrea]

Released at v2.4.0.

The option has been renamed to rehype.githubAlerts to more accurately reflect that it only transforms admonitions written in GitHub format.

Thanks again @FrankLedo !