Is your feature request related to a problem? Please describe.
In modern development workflows, it is best practice to maintain documentation entirely in Markdown files within the repository, automating publication to Confluence via CI/CD pipelines. However, I'm always frustrated because Markdown lacks standard ways to trigger native Confluence dynamic features, like a Table of Contents (TOC) or a Children Display list. To use them, we currently have to mix raw Confluence XML storage format inside our Markdown files, which breaks the local documentation readability and portability.
Describe the solution you'd like
I would like the CLI to support special triggers to automatically inject standard Confluence macros during the pipeline execution, inspired by the md2conf project. Since this CLI handles both Markdown and HTML, a very clean approach would be to support special HTML comments as triggers, alongside text tags. HTML comments are ignored by standard Markdown viewers (like GitHub preview) but can be easily parsed by the CLI before publishing.
Ideally, the CLI could support both the md2conf text syntax and an HTML comment alternative:
- Table of Contents Macro
- Text syntax: [[TOC]]
- HTML comment syntax: - Target Confluence Storage Format: <ac:structured-macro ac:name="toc" ac:schema-version="1" />
- Children Display Macro (Child pages listing)
- Text syntax: [[LISTING]]
- HTML comment syntax: - Target Confluence Storage Format: <ac:structured-macro ac:name="children" ac:schema-version="2" />
Describe alternatives you've considered
The current alternative is manually pasting raw XML macro blocks into the Markdown files, which defeats the purpose of keeping a clean, platform-agnostic Markdown documentation base in the repository.
Use case
This feature would be used by teams managing "documentation as code" via automated deployment pipelines. Developers can write standard, clean Markdown in their repository, while the publishing pipeline automatically expands the special tags/comments into native Confluence macros for the end-users.
Additional context
The md2conf tool proved that the [[TOC]] and [[LISTING]] conventions are highly requested by users who automate Confluence publishing. Adding the HTML comment variant builds upon that idea, offering a native web-standard way to embed this metadata without breaking Markdown environments.
Implementation suggestions
During the pre-processing or parsing stage, a regex pass could look for both the text patterns ([[TOC]], [[LISTING]]) and the HTML comment patterns (, ). The CLI would then replace these placeholders with their respective Confluence XHTML macro structures before sending the API payload.
Is your feature request related to a problem? Please describe.
In modern development workflows, it is best practice to maintain documentation entirely in Markdown files within the repository, automating publication to Confluence via CI/CD pipelines. However, I'm always frustrated because Markdown lacks standard ways to trigger native Confluence dynamic features, like a Table of Contents (TOC) or a Children Display list. To use them, we currently have to mix raw Confluence XML storage format inside our Markdown files, which breaks the local documentation readability and portability.
Describe the solution you'd like
I would like the CLI to support special triggers to automatically inject standard Confluence macros during the pipeline execution, inspired by the md2conf project. Since this CLI handles both Markdown and HTML, a very clean approach would be to support special HTML comments as triggers, alongside text tags. HTML comments are ignored by standard Markdown viewers (like GitHub preview) but can be easily parsed by the CLI before publishing.
Ideally, the CLI could support both the md2conf text syntax and an HTML comment alternative:
Describe alternatives you've considered
The current alternative is manually pasting raw XML macro blocks into the Markdown files, which defeats the purpose of keeping a clean, platform-agnostic Markdown documentation base in the repository.
Use case
This feature would be used by teams managing "documentation as code" via automated deployment pipelines. Developers can write standard, clean Markdown in their repository, while the publishing pipeline automatically expands the special tags/comments into native Confluence macros for the end-users.
Additional context
The md2conf tool proved that the [[TOC]] and [[LISTING]] conventions are highly requested by users who automate Confluence publishing. Adding the HTML comment variant builds upon that idea, offering a native web-standard way to embed this metadata without breaking Markdown environments.
Implementation suggestions
During the pre-processing or parsing stage, a regex pass could look for both the text patterns ([[TOC]], [[LISTING]]) and the HTML comment patterns (, ). The CLI would then replace these placeholders with their respective Confluence XHTML macro structures before sending the API payload.