feat(#70): Github Alerts (#72)

* feat(#70): Add GitHub alerts transformation to Confluence macros
---------

Co-authored-by: frankledo <[email protected]>
Co-authored-by: Frank Ledo <[email protected]>

Author: javierbrea

components/cspell-config/dictionaries/missing-en.txt

@@ -0,0 +1 @@
+blockquotes

components/markdown-confluence-sync/CHANGELOG.md

@@ -11,10 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Deprecated
 #### Removed
 
-## Unreleased
+## [2.4.0] - 2025-11-27
 
 #### Added
 
+* feat(#70): Add GitHub alerts transformation to Confluence macros.
+  GitHub-flavored markdown alerts ([!NOTE], [!TIP], [!IMPORTANT],
+  [!WARNING], [!CAUTION]) are now converted to Confluence's native
+  info, note, warning, and tip macros. This feature is disabled by
+  default and can be enabled via `rehype.alerts` configuration option.
+
 ## [2.3.0] - 2025-11-24
 
 #### Added

components/markdown-confluence-sync/README.md

@@ -303,6 +303,7 @@ The namespace for the configuration of this library is `markdown-confluence-sync
 | `confluence.noticeTemplate` | `string` | Template string to use for the notice message. | |
 | `confluence.dryRun` | `boolean` | Log create, update or delete requests to Confluence instead of really making them | `false` |
 | `rehype.codeBlocks` | `boolean` | Enable conversion of code blocks to Confluence code macro format with syntax highlighting. When disabled, code blocks remain as plain HTML pre/code tags. | `false` |
+| `rehype.githubAlerts` | `boolean` | Enable conversion of GitHub alerts ([!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) to Confluence info/note/warning/tip macros. When disabled, github alerts remain as blockquotes. | `false` |
 | `dryRun` | `boolean` | Process markdown files without sending them to `confluence-sync`. Useful to early detection of possible errors in configuration, etc. Note that, requests that would be made to Confluence won't be logged, use `confluence.dryRun` for that, which also connects to Confluence to calculate the requests to do | `false` |
 | `config.readArguments` | `boolean` | Read configuration from arguments or not | `false` |
 | `config.readFile` | `boolean` | Read configuration from file or not | `false` |
@@ -495,7 +496,7 @@ Apart of supporting the most common markdown features, the library also supports
       <ac:rich-text-body><p>This is the content of the details.</p></ac:rich-text-body>
     </ac:structured-macro>
     ```
-* Code blocks - Markdown fenced code blocks can be converted to
+* [Code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) - Markdown fenced code blocks can be converted to
   Confluence code macro format with syntax highlighting support. This
   feature is disabled by default but can be enabled via the
   `rehype.codeBlocks` configuration option.
@@ -519,6 +520,33 @@ Apart of supporting the most common markdown features, the library also supports
       <ac:plain-text-body><![ CDATA [ const hello = "world";console.log(hello);] ]></ac:plain-text-body>
     </ac:structured-macro>
     ```
+* [GitHub Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) - GitHub-flavored markdown alerts can be converted to
+  Confluence's native info, note, warning, and tip macros. This feature
+  is disabled by default but can be enabled via the `rehype.githubAlerts`
+  configuration option.
+  * The plugin converts GitHub alert syntax (`[!NOTE]`, `[!TIP]`,
+    `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`) to appropriate
+    Confluence macros.
+  * Alert content including formatted text, code, and lists is
+    preserved in the conversion.
+  * This feature is disabled by default for backward compatibility.
+    Enable it by setting `rehype.githubAlerts: true`.
+  * For example, the following markdown alert:
+    ```markdown
+    > [!NOTE]
+    > Useful information that users should know, even when skimming
+    > content.
+    ```
+    will be converted to a Confluence info macro as follows:
+    ```markdown
+    <ac:structured-macro ac:name="info">
+      <ac:parameter ac:name="title">Note</ac:parameter>
+      <ac:rich-text-body>
+        <p>Useful information that users should know, even when skimming
+        content.</p>
+      </ac:rich-text-body>
+    </ac:structured-macro>
+    ```
 
 ### Unsupported features
 

components/markdown-confluence-sync/markdown-confluence-sync.config.cjs

@@ -43,5 +43,6 @@ module.exports = {
   logLevel: "debug",
   rehype: {
     codeBlocks: true,
+    githubAlerts: true,
   },
 };

components/markdown-confluence-sync/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@telefonica/markdown-confluence-sync",
   "description": "Creates/updates/deletes Confluence pages based on markdown files in a directory. Supports Mermaid diagrams and per-page configuration using frontmatter metadata. Works great with Docusaurus",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "license": "Apache-2.0",
   "author": "Telefónica Innovación Digital",
   "repository": {

components/markdown-confluence-sync/src/lib/confluence/ConfluenceSync.ts

@@ -36,6 +36,8 @@ import type {
   AuthenticationOption,
   RehypeCodeBlocksOptionDefinition,
   RehypeCodeBlocksOption,
+  RehypeGithubAlertsOptionDefinition,
+  RehypeGithubAlertsOption,
   ApiPrefixOption,
   ApiPrefixOptionDefinition,
 } from "./ConfluenceSync.types.js";
@@ -101,6 +103,12 @@ const rehypeCodeBlocksOption: RehypeCodeBlocksOptionDefinition = {
   default: false,
 };
 
+const rehypeGithubAlertsOption: RehypeGithubAlertsOptionDefinition = {
+  name: "githubAlerts",
+  type: "boolean",
+  default: false,
+};
+
 export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
   implements ConfluenceSyncInterface
 {
@@ -120,6 +128,7 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
   private _logger: LoggerInterface;
   private _modeOption: ModeOption;
   private _rehypeCodeBlocksOption: RehypeCodeBlocksOption;
+  private _rehypeGithubAlertsOption: RehypeGithubAlertsOption;
 
   constructor({ config, rehypeConfig, logger, mode }: ConfluenceSyncOptions) {
     this._urlOption = config.addOption(urlOption) as UrlOption;
@@ -151,6 +160,10 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
       rehypeCodeBlocksOption,
     ) as RehypeCodeBlocksOption;
 
+    this._rehypeGithubAlertsOption = rehypeConfig.addOption(
+      rehypeGithubAlertsOption,
+    ) as RehypeGithubAlertsOption;
+
     this._modeOption = mode;
     this._logger = logger;
   }
@@ -220,6 +233,7 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
         logger: this._logger.namespace("transformer"),
         rehype: {
           codeBlocks: this._rehypeCodeBlocksOption.value,
+          githubAlerts: this._rehypeGithubAlertsOption.value,
         },
       });
 

components/markdown-confluence-sync/src/lib/confluence/ConfluenceSync.types.ts

@@ -25,6 +25,7 @@ type NoticeTemplateOptionValue = string;
 type DryRunOptionValue = boolean;
 
 type RehypeCodeBlocksOptionValue = boolean;
+type RehypeGithubAlertsOptionValue = boolean;
 
 declare global {
   //eslint-disable-next-line @typescript-eslint/no-namespace
@@ -58,6 +59,8 @@ declare global {
       rehype?: {
         /** Enable code blocks transformation to Confluence code macro */
         codeBlocks?: RehypeCodeBlocksOptionValue;
+        /** Enable GitHub alerts transformation to Confluence info/note/warning/tip macros */
+        githubAlerts?: RehypeGithubAlertsOptionValue;
       };
     }
   }
@@ -82,6 +85,8 @@ export type DryRunOptionDefinition = OptionDefinition<
 >;
 export type RehypeCodeBlocksOptionDefinition =
   OptionDefinition<RehypeCodeBlocksOptionValue>;
+export type RehypeGithubAlertsOptionDefinition =
+  OptionDefinition<RehypeGithubAlertsOptionValue>;
 
 export type AuthenticationOptionDefinition =
   OptionDefinition<ConfluenceClientAuthenticationConfig>;
@@ -109,6 +114,11 @@ export type RehypeCodeBlocksOption = OptionInterfaceOfType<
   { hasDefault: true }
 >;
 
+export type RehypeGithubAlertsOption = OptionInterfaceOfType<
+  RehypeGithubAlertsOptionValue,
+  { hasDefault: true }
+>;
+
 export interface ConfluenceSyncOptions {
   /** Configuration interface */
   config: ConfigNamespaceInterface;

components/markdown-confluence-sync/src/lib/confluence/transformer/ConfluencePageTransformer.ts

@@ -27,6 +27,7 @@ import { InvalidTemplateError } from "./errors/InvalidTemplateError.js";
 import rehypeAddAttachmentsImages from "./support/rehype/rehype-add-attachments-images.js";
 import type { ImagesMetadata } from "./support/rehype/rehype-add-attachments-images.types.js";
 import rehypeAddNotice from "./support/rehype/rehype-add-notice.js";
+import rehypeReplaceGithubAlerts from "./support/rehype/rehype-replace-github-alerts.js";
 import rehypeReplaceCodeBlocks from "./support/rehype/rehype-replace-code-blocks.js";
 import rehypeReplaceDetails from "./support/rehype/rehype-replace-details.js";
 import rehypeReplaceImgTags from "./support/rehype/rehype-replace-img-tags.js";
@@ -52,14 +53,15 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
   private readonly _spaceKey: string;
   private readonly _logger?: LoggerInterface;
   private readonly _rehypeCodeBlocksEnabled: boolean;
+  private readonly _rehypeGithubAlertsEnabled: boolean;
 
   constructor({
     noticeMessage,
     noticeTemplate,
     rootPageName,
     spaceKey,
     logger,
-    rehype: { codeBlocks },
+    rehype: { codeBlocks, githubAlerts },
   }: ConfluencePageTransformerOptions) {
     this._noticeMessage = noticeMessage;
     this._noticeTemplateRaw = noticeTemplate;
@@ -70,9 +72,10 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
     this._spaceKey = spaceKey;
     this._logger = logger;
     this._rehypeCodeBlocksEnabled = codeBlocks ?? false;
+    this._rehypeGithubAlertsEnabled = githubAlerts ?? false;
 
     logger?.debug(
-      `ConfluencePageTransformer initialized with rehype options: ${JSON.stringify({ codeBlocks: this._rehypeCodeBlocksEnabled })}`,
+      `ConfluencePageTransformer initialized with rehype options: ${JSON.stringify({ codeBlocks: this._rehypeCodeBlocksEnabled, alerts: this._rehypeGithubAlertsEnabled })}`,
     );
   }
 
@@ -117,6 +120,12 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
         processor = processor.use(rehypeReplaceCodeBlocks);
       }
 
+      // Conditionally add alerts plugin
+      if (this._rehypeGithubAlertsEnabled) {
+        this._logger?.debug(`Registering rehypeReplaceAlerts plugin`);
+        processor = processor.use(rehypeReplaceGithubAlerts);
+      }
+
       const content = processor
         .use(rehypeAddAttachmentsImages)
         .use(rehypeReplaceImgTags)

components/markdown-confluence-sync/src/lib/confluence/transformer/ConfluencePageTransformer.types.ts

@@ -18,6 +18,14 @@ export interface ConfluencePageTransformerRehypeOptions {
    * @default false
    */
   codeBlocks?: boolean;
+  /**
+   * Enable GitHub alerts transformation to Confluence info/note/warning/tip macros.
+   * When enabled, GitHub-flavored markdown alerts (e.g., [!NOTE], [!WARNING])
+   * will be converted to appropriate Confluence macro format.
+   * When this option is not specified or set to false, alerts will remain as blockquotes.
+   * @default false
+   */
+  githubAlerts?: boolean;
 }
 
 export interface ConfluencePageTransformerOptions {