[Feature]: External plugin support

[survik1]

Package

markdown-confluence-sync

Description

Hi! I’m exploring ways to add more Confluence macro support during MD -> ADF conversion. Right now this seems to require a small refactor so plugins can be injected/configured rather than hard-coded.

Specifically, ConfluencePageTransformer imports its plugins statically, which prevents users from adding their own without forking the library - even though the internal plugin mechanism already exists. A concrete use-case is inserting a TOC macro (e.g. Confluence Table of contents) via a simple Unified plugin.

It would be great if you could modify the library to allow external plugins. I can dedicate some company time to help with an implementation, if you can share a brief design direction (as we are primarly backend developers),

Suggested Solution

Code of Conduct

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

[javierbrea]

Hi @survik1 , thanks a lot for taking the time to open this feature request, and sorry for the very late response.

At the moment, the only extensibility point we expose is the preprocessor hook, which runs before the Markdown is parsed and converted, so it can only do text-level transformations and is not suitable for AST-level plugins or integrations with the unified/remark/rehype ecosystem.

Proposed implementation (JS config only)

My current idea is to support external plugins only when using a JavaScript config file (for example markdown-confluence-sync.config.cjs / .mjs / .js), and allow passing actual plugin functions there:

// markdown-confluence-sync.config.js
const myRemarkPlugin = require("my-remark-plugin");
const myRehypePlugin = require("my-rehype-plugin");

module.exports = {
  // existing options...
  remarkPlugins: [
    // same shape as unified/remark: [plugin, options?]
    [myRemarkPlugin, { /* options */ }],
  ],
  rehypePlugins: [
    [myRehypePlugin, { /* options */ }],
  ],
};

Restricting this to JS config avoids having @telefonica/markdown-confluence-sync dynamically import user modules from JSON/YAML/env-based configuration, which tends to introduce a lot of complexity and edge cases around ESM vs CJS, TypeScript transpilation, and sometimes even pushes tools to bundle extra loaders/transpilers (like Babel) into the core just to be able to load user code. That’s something I’d like to avoid in this library in order to keep the core small, predictable, and environment-agnostic.

For the same reason, I’m inclined to not support a “serializable” plugin configuration where the library resolves module names or file paths from JSON/YAML and imports them internally. In practice this quickly runs into:

• Different module systems (CJS/ESM) and runtime resolution differences.
• TypeScript configs that require a build step.
• Tooling-specific conventions that are hard to support in a generic library.

Instead, keeping “user code loading” entirely under the user’s control (in their JS config) keeps the responsibilities clear and avoids adding that complexity to the core.

Plugin ordering

For plugin ordering, we can follow a model similar to Webpack’s approach where plugins are applied in the order they appear in the config arrays, and the execution order is therefore explicit and user-controlled.

Concretely, we could:

• Keep the built-in plugins in an internal array.
• Allow the user to specify where their plugins should run via a simple “position” hint, for example:

const myRemarkPlugin = require("my-remark-plugin");

module.exports = {
  remarkPlugins: [
    // run before built-ins
    { plugin: myRemarkPlugin, options: { /* ... */ }, position: "before" },
  ],
};

Under the hood, the library would merge:

• position: "before" plugins, then
• the built-in set, then
• position: "after" plugins,

while preserving the relative order within each group.

Alternatively (and simpler), we could expose two explicit arrays:

module.exports = {
  remarkPluginsBefore: [
    // user plugins before built-ins
  ],
  remarkPluginsAfter: [
    // user plugins after built-ins
  ],
};

and use the plain array order inside each one as the execution order.

Next steps

If this design looks reasonable to you and fits your requirements, feel free to open a draft PR with an initial implementation based on this proposal, and we can refine it together there. Or don’t hesitate to add any alternative ideas or improvements to this design directly in this issue.

Thanks again!