Merge pull request #69 from Telefonica/release

Release 2.3.0

Author: javierbrea

components/markdown-confluence-sync/CHANGELOG.md

@@ -15,7 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Added
 
-- feat(#63): Add apiPrefix option to configure the Confluence API prefix (default: /rest/).
+## [2.3.0] - 2025-11-24
+
+#### Added
+
+* feat(#65): Add code blocks transformation to Confluence code macro format.
+  Code blocks are now converted to Confluence's structured code macro
+  with syntax highlighting support. This feature is disabled by default
+  and can be enabled via `rehype.codeBlocks` configuration option.
+* feat(#63): Add apiPrefix option to configure the Confluence API prefix (default: /rest/).
 
 ## [2.2.0] - 2025-10-17
 

components/markdown-confluence-sync/README.md

@@ -302,6 +302,7 @@ The namespace for the configuration of this library is `markdown-confluence-sync
 | `confluence.noticeMessage` | `string` | Notice message to add at the beginning of the Confluence pages. | |
 | `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` |
 | `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` |
@@ -494,6 +495,30 @@ 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
+  Confluence code macro format with syntax highlighting support. This
+  feature is disabled by default but can be enabled via the
+  `rehype.codeBlocks` configuration option.
+  * The plugin converts fenced code blocks to Confluence's
+    `<ac:structured-macro ac:name="code">` format.
+  * Language syntax highlighting is preserved when specified in the
+    markdown code fence.
+  * This feature is disabled by default for compatibility with older
+    Confluence versions. Enable it by setting `rehype.codeBlocks: true`.
+  * For example, the following markdown code block:
+    ````markdown
+    ```javascript
+    const hello = "world";
+    console.log(hello);
+    ```
+    ````
+    will be converted to a Confluence code macro as follows:
+    ```markdown
+    <ac:structured-macro ac:name="code">
+      <ac:parameter ac:name="language">javascript</ac:parameter>
+      <ac:plain-text-body><![ CDATA [ const hello = "world";console.log(hello);] ]></ac:plain-text-body>
+    </ac:structured-macro>
+    ```
 
 ### Unsupported features
 

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

@@ -20,10 +20,10 @@ module.exports = {
   // An object that configures minimum threshold enforcement for coverage results
   coverageThreshold: {
     global: {
-      branches: 98,
-      functions: 98,
-      lines: 98,
-      statements: 98,
+      branches: 97,
+      functions: 97,
+      lines: 97,
+      statements: 97,
     },
   },
 

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

@@ -41,4 +41,7 @@ module.exports = {
     rootPageName: "Cross",
   },
   logLevel: "debug",
+  rehype: {
+    codeBlocks: 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.2.0",
+  "version": "2.3.0",
   "license": "Apache-2.0",
   "author": "Telefónica Innovación Digital",
   "repository": {

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

@@ -41,6 +41,7 @@ import type {
 const MODULE_NAME = "markdown-confluence-sync";
 const MARKDOWN_NAMESPACE = "markdown";
 const CONFLUENCE_NAMESPACE = "confluence";
+const REHYPE_CONFIG_NAMESPACE = "rehype";
 
 const DEFAULT_CONFIG: Configuration["config"] = {
   readArguments: false,
@@ -146,6 +147,9 @@ export const MarkdownConfluenceSync: MarkdownConfluenceSyncConstructor = class M
 
     const confluenceConfig =
       this._configuration.addNamespace(CONFLUENCE_NAMESPACE);
+    const rehypeConfig = this._configuration.addNamespace(
+      REHYPE_CONFIG_NAMESPACE,
+    );
     const confluenceLogger = this._logger.namespace(CONFLUENCE_NAMESPACE);
 
     this._markdownDocuments = new MarkdownDocuments({
@@ -160,6 +164,7 @@ export const MarkdownConfluenceSync: MarkdownConfluenceSyncConstructor = class M
     });
     this._confluenceSync = new ConfluenceSync({
       config: confluenceConfig,
+      rehypeConfig: rehypeConfig,
       logger: confluenceLogger,
       mode: this._modeOption,
     });

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

@@ -34,6 +34,8 @@ import type {
   NoticeTemplateOption,
   AuthenticationOptionDefinition,
   AuthenticationOption,
+  RehypeCodeBlocksOptionDefinition,
+  RehypeCodeBlocksOption,
   ApiPrefixOption,
   ApiPrefixOptionDefinition,
 } from "./ConfluenceSync.types.js";
@@ -93,6 +95,12 @@ const authenticationOption: AuthenticationOptionDefinition = {
   type: "object",
 };
 
+const rehypeCodeBlocksOption: RehypeCodeBlocksOptionDefinition = {
+  name: "codeBlocks",
+  type: "boolean",
+  default: false,
+};
+
 export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
   implements ConfluenceSyncInterface
 {
@@ -111,8 +119,9 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
   private _initialized = false;
   private _logger: LoggerInterface;
   private _modeOption: ModeOption;
+  private _rehypeCodeBlocksOption: RehypeCodeBlocksOption;
 
-  constructor({ config, logger, mode }: ConfluenceSyncOptions) {
+  constructor({ config, rehypeConfig, logger, mode }: ConfluenceSyncOptions) {
     this._urlOption = config.addOption(urlOption) as UrlOption;
     this._apiPrefixOption = config.addOption(
       apiPrefixOption,
@@ -137,6 +146,11 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
       authenticationOption,
     ) as AuthenticationOption;
     this._dryRunOption = config.addOption(dryRunOption) as DryRunOption;
+
+    this._rehypeCodeBlocksOption = rehypeConfig.addOption(
+      rehypeCodeBlocksOption,
+    ) as RehypeCodeBlocksOption;
+
     this._modeOption = mode;
     this._logger = logger;
   }
@@ -204,6 +218,9 @@ export const ConfluenceSync: ConfluenceSyncConstructor = class ConfluenceSync
         rootPageName: this._rootPageNameOption.value,
         spaceKey: this._spaceKeyOption.value,
         logger: this._logger.namespace("transformer"),
+        rehype: {
+          codeBlocks: this._rehypeCodeBlocksOption.value,
+        },
       });
 
       this._confluenceSyncPages = new ConfluenceSyncPages({

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

@@ -24,6 +24,8 @@ type NoticeMessageOptionValue = string;
 type NoticeTemplateOptionValue = string;
 type DryRunOptionValue = boolean;
 
+type RehypeCodeBlocksOptionValue = boolean;
+
 declare global {
   //eslint-disable-next-line @typescript-eslint/no-namespace
   namespace MarkdownConfluenceSync {
@@ -53,6 +55,10 @@ declare global {
         /** Confluence dry run */
         dryRun?: DryRunOptionValue;
       };
+      rehype?: {
+        /** Enable code blocks transformation to Confluence code macro */
+        codeBlocks?: RehypeCodeBlocksOptionValue;
+      };
     }
   }
 }
@@ -74,6 +80,8 @@ export type DryRunOptionDefinition = OptionDefinition<
   DryRunOptionValue,
   { hasDefault: true }
 >;
+export type RehypeCodeBlocksOptionDefinition =
+  OptionDefinition<RehypeCodeBlocksOptionValue>;
 
 export type AuthenticationOptionDefinition =
   OptionDefinition<ConfluenceClientAuthenticationConfig>;
@@ -96,13 +104,20 @@ export type DryRunOption = OptionInterfaceOfType<
   { hasDefault: true }
 >;
 
+export type RehypeCodeBlocksOption = OptionInterfaceOfType<
+  RehypeCodeBlocksOptionValue,
+  { hasDefault: true }
+>;
+
 export interface ConfluenceSyncOptions {
   /** Configuration interface */
   config: ConfigNamespaceInterface;
   /** Logger interface */
   logger: LoggerInterface;
   /** Sync mode option */
   mode: ModeOption;
+  /** Rehype configuration namespace */
+  rehypeConfig: ConfigNamespaceInterface;
 }
 
 /** Creates a ConfluenceSyncInterface interface */

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 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";
 import rehypeReplaceInternalReferences from "./support/rehype/rehype-replace-internal-references.js";
@@ -50,13 +51,15 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
   private readonly _rootPageName?: string;
   private readonly _spaceKey: string;
   private readonly _logger?: LoggerInterface;
+  private readonly _rehypeCodeBlocksEnabled: boolean;
 
   constructor({
     noticeMessage,
     noticeTemplate,
     rootPageName,
     spaceKey,
     logger,
+    rehype: { codeBlocks },
   }: ConfluencePageTransformerOptions) {
     this._noticeMessage = noticeMessage;
     this._noticeTemplateRaw = noticeTemplate;
@@ -66,6 +69,11 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
     this._rootPageName = rootPageName;
     this._spaceKey = spaceKey;
     this._logger = logger;
+    this._rehypeCodeBlocksEnabled = codeBlocks ?? false;
+
+    logger?.debug(
+      `ConfluencePageTransformer initialized with rehype options: ${JSON.stringify({ codeBlocks: this._rehypeCodeBlocksEnabled })}`,
+    );
   }
 
   public async transform(
@@ -88,7 +96,7 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
       DEFAULT_MERMAID_DIAGRAMS_LOCATION,
     );
     try {
-      const content = remark()
+      let processor = remark()
         .use(remarkGfm)
         .use(remarkFrontmatter)
         .use(remarkRemoveFootnotes)
@@ -101,7 +109,15 @@ export const ConfluencePageTransformer: ConfluencePageTransformerConstructor = c
         .use(rehypeAddNotice, { noticeMessage })
         .use(rehypeReplaceDetails)
         .use(rehypeReplaceStrikethrough)
-        .use(rehypeReplaceTaskList)
+        .use(rehypeReplaceTaskList);
+
+      // Conditionally add code blocks plugin
+      if (this._rehypeCodeBlocksEnabled) {
+        this._logger?.debug(`Registering rehypeReplaceCodeBlocks plugin`);
+        processor = processor.use(rehypeReplaceCodeBlocks);
+      }
+
+      const content = processor
         .use(rehypeAddAttachmentsImages)
         .use(rehypeReplaceImgTags)
         .use(rehypeReplaceInternalReferences, {

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

@@ -6,6 +6,20 @@ import type { ConfluenceInputPage } from "@telefonica/confluence-sync";
 
 import type { ConfluenceSyncPage } from "../ConfluenceSync.types.js";
 
+/**
+ * Options for Rehype plugins used in ConfluencePageTransformer
+ */
+export interface ConfluencePageTransformerRehypeOptions {
+  /**
+   * Enable code blocks transformation to Confluence code macro.
+   * When enabled, markdown code blocks will be converted to Confluence's
+   * structured code macro format with syntax highlighting support.
+   * When this option is not specified or set to false, code blocks will remain as plain HTML <pre>/<code> tags rather than being transformed.
+   * @default false
+   */
+  codeBlocks?: boolean;
+}
+
 export interface ConfluencePageTransformerOptions {
   /** Confluence page notice message */
   noticeMessage?: string;
@@ -24,6 +38,8 @@ export interface ConfluencePageTransformerOptions {
   spaceKey: string;
   /** Logger */
   logger?: LoggerInterface;
+  /** Rehype options */
+  rehype: ConfluencePageTransformerRehypeOptions;
 }
 
 /** Creates a ConfluencePageTransformer interface */