Supported Extensions & Macros

acp2md converts Atlassian Document Format (ADF) through the Climakers conversion engine. That engine recognises a broad catalogue of Confluence extensions, marketplace-app macros, embeds and media types, and decides element by element whether to render real content fetched from Confluence or to preserve the original element as a safe HTML comment.

How an extension is rendered

Every recognised extension goes through three possible outcomes, in order:

1. Live API rendering. The --ext-* or --embed-* flag is enabled and the required credentials and context (space key, page ID) are available. The macro is replaced with real content: a Markdown table, a list of resolved pages, a base64 image.
2. HTML-comment placeholder. The extension is disabled, credentials are missing, or the API call failed. The converter emits a comment such as <!-- Page Tree -->. It is invisible in rendered Markdown but records that a macro existed at that position, so audit and migration workflows stay lossless.
3. Graceful fallback. For image-style extensions, a failed download falls back to a plain reference — media://UUID or the original Confluence URL — so the document is never broken.

What Confluence access each extension needs

Most extensions need API access to resolve content. Configure it once through the config file, environment variables, or persistent flags — see Configuration.

When credentials or context are missing for one extension, only that extension degrades to an HTML comment and a warning is logged. Every other extension on the page continues to render.

Support matrix

The canonical inventory. Flag names are the CLI form accepted by acs2md and acp2md.

Images and media

Inline images

--embed-images (default true) downloads every remote image the page references and embeds it as a base64 data URI. The resulting Markdown is self-contained: it does not depend on the Confluence host, a private CDN, or network access at reading time.

Embedded: files with image extensions (.png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .ico), known image hosts, and any URL whose Content-Type starts with image/.

Skipped on purpose: YouTube and other video URLs, HTML pages, PDFs and other non-image binaries.

Base64 adds roughly 33% to the byte size — the normal cost of a self-contained document.

Confluence-hosted media files

ADF represents uploaded images, avatars and icons as media nodes carrying a UUID and a collection reference like contentId-393325. Without API access those can only render as media://UUID placeholders.

With --embed-media-images on and credentials configured, acp2md extracts the page ID from the collection attribute, calls the attachments API once per page (cached), downloads each matched attachment, and embeds it. A failed download falls back to ![](media://UUID) rather than breaking the document.

Supported formats: PNG, JPEG, GIF, WebP, SVG, BMP, ICO.

Sidecar files instead of base64

--image-sidecars writes the bytes to attachments/<page-id>/<filename> and links them relatively:

![image-20240930-142031.png](attachments/5814878215/image-20240930-142031.png)

The export stays self-contained either way — what changes is line length. See Obsidian Vaults for why a 100 KB single-line data URI stops rendering there but works on GitHub. Failures fall back to base64, then to the remote URL.

Non-image attachments

PDFs, .docx, .xlsx, .pptx, ZIP archives and similar resolve through the same attachments API but render as ordinary Markdown links. The bytes are downloaded once and saved beside the Markdown:

[MBR Conversion User Guide.pdf](attachments/5814878215/MBR%20Conversion%20User%20Guide.pdf)
[Quarterly KPI workbook.xlsx](attachments/5814878215/Quarterly%20KPI%20workbook.xlsx)

• Files land at attachments/<page-id>/<original-filename>, so attachments from many pages share one output directory without colliding.
• Original filenames are preserved; characters unsafe on Linux, macOS or Windows are replaced with _. Hrefs are percent-encoded, so spaces and parentheses still produce working links.
• An existing destination file is not re-downloaded — the filesystem acts as the cache.
• A failed download falls back to the remote Confluence URL with a warning, so output is never broken.

File type is classified by Confluence’s reported media type first, then magic-byte sniffing (PDF, ZIP / Office Open XML, OLE, RTF, 7z, gzip, tar), then the filename extension.

Diagrams

Both need Confluence credentials, because the rendered image is fetched from the tenant rather than reconstructed locally. Both fall back to an HTML comment when they cannot be resolved.

Page-listing macros

acp2md converts a single page, so it has the page ID but not the space key. Pass --space-key when the page uses Recently Updated, List Labels, Blog Posts or Content by Label — without it those macros degrade to HTML comments.

People, activity and reporting

Document control and quality

These resolve template placeholders into the page’s actual metadata, which is what makes a converted controlled document readable outside Confluence.

Cards and embeds

Inline card resolution is also what --wikilinks builds on: it needs a real title before it can emit [[Page Title]].

Lossless fallback

Anchors, excerpts, bodied extensions (expand and friends), inline extensions (status, livesearch), and any macro the engine does not specifically support are preserved as HTML comments. Nothing is silently dropped — a migration audit can still find every position where a macro used to be.

Markdown standards compliance

Output is written to satisfy common Markdown linters:

Extended syntax preserved by GitHub, Obsidian and Pandoc is also emitted: highlight, superscript and subscript, automatic URL linking, per-column GFM table alignment, panels as alerts or callouts (--panel-style), math ($…$ and $$…$$), heading IDs for anchor links, and footnotes.

Caching, size limits and credentials

Several extensions download bytes or issue REST calls. Two settings control how aggressively results are cached:

Attachment sidecars use the output directory itself as a cache: a file already on disk is not fetched again.

When --sync or --incremental is active, acp2md prints both the state file path and the image cache path before conversion starts, so you can confirm where artefacts will land.

When to disable an extension

Each --ext-render-* costs extra API calls, because the macro is resolved against Confluence rather than read from the page body. On a page dense with macros that dominates the conversion time.

See also

• Convert Pages — the full flag reference
• Obsidian Vaults — how these render in a vault
• Configuration — credentials, proxy and retry settings