Configuration options¶

Reference for every supported option. All options can be set via cme config set <key>=<value> or overridden per-session through the listed environment variable.

export.*¶

export.log_level¶

Controls output verbosity: DEBUG (every step), INFO (key milestones), WARNING (warnings/errors only), ERROR (errors only).

• Default: INFO
• ENV Var: CME_EXPORT__LOG_LEVEL

export.save_log_to_file¶

Also write log records to cme.log next to the config file (see cme config path). Useful for capturing long DEBUG runs.

• Default: False
• ENV Var: CME_EXPORT__SAVE_LOG_TO_FILE

export.output_path¶

The directory where all exported files and folders will be written. Used as the base for relative and absolute links.

• Default: ./ (current working directory)
• ENV Var: CME_EXPORT__OUTPUT_PATH

export.page_href¶

How to generate links to pages in Markdown. Options: relative (default), absolute, or wiki.

• Default: relative
• ENV Var: CME_EXPORT__PAGE_HREF

The link label is the link text as written on the Confluence page. When it differs from the target page title, wiki emits an alias ([[Page Title|link text]]). If the link has no text, or the text is just the target URL, the page title is used instead.

export.page_href_relative_only_if_ancestor_of¶

Limits local links (relative, absolute or wiki) to the given page and its descendants. Links to any other page stay absolute Confluence URLs. Useful when exporting only a section of a space: links into the rest of the space keep pointing at Confluence instead of at files that are not exported.

Must be the numeric page ID. URLs are not supported.

• Default: None
• ENV Var: CME_EXPORT__PAGE_HREF_RELATIVE_ONLY_IF_ANCESTOR_OF

export.page_path¶

Path template for exported pages.

• Default: {space_name}/{homepage_title}/{ancestor_titles}/{page_title}.md
• ENV Var: CME_EXPORT__PAGE_PATH

export.page_path_if_parent¶

Overrides export.page_path for pages that have child pages.

• Default: None, in which case export.page_path is used.
• ENV Var: CME_EXPORT__PAGE_PATH_IF_PARENT

Useful for exporting parent pages as README.md/index.md inside a directory named after the page. Renderers such as GitHub, GitLab, MkDocs and Docusaurus treat that file as the directory's content. Deciding whether a page has children costs one API request per page, so the check only runs when this option is set.

Example usage, together with export.attachment_path_if_parent:

export.page_path                 = {ancestor_titles}/{page_title}.md
export.page_path_if_parent       = {ancestor_titles}/{page_title}/README.md
export.attachment_path           = {ancestors_without_last}/_assets/{attachment_title}{attachment_extension}
export.attachment_path_if_parent = {ancestor_titles}/_assets/{attachment_title}{attachment_extension}

├── _assets
│   └── diagram_a.png            # linked from PageA
├── PageB
│   ├── _assets
│   │      ├── diagram_b.png     # Linked from PageB  (now PageB/README.md)
│   │      └── diagram_c.png     # Linked from PageC
│   ├── PageC.md
│   └── README.md                # In confluence this was PageB
└── PageA.md                     # No child pages, so it keeps the regular page_path

export.attachment_href¶

How to generate links to attachments in Markdown. Options: relative (default), absolute, or wiki.

• Default: relative
• ENV Var: CME_EXPORT__ATTACHMENT_HREF

export.attachment_path¶

Path template for attachments.

• Default: {space_name}/attachments/{attachment_file_id}{attachment_extension}
• ENV Var: CME_EXPORT__ATTACHMENT_PATH

On Confluence Data Center / Server, where the API does not provide fileId, {attachment_file_id} falls back to the content id, so the default template still produces unique filenames.

export.attachment_path_if_parent¶

Overrides export.attachment_path for attachments on pages that have child pages.

• Default: None, in which case export.attachment_path is used
• ENV Var: CME_EXPORT__ATTACHMENT_PATH_IF_PARENT

See export.page_path_if_parent for example usage.

export.attachments_export¶

Which attachments to download to disk.

• Default: referenced
• ENV Var: CME_EXPORT__ATTACHMENTS_EXPORT

export.image_captions¶

Whether to export Confluence image captions in the exported Markdown. When enabled, the storage format of each page is fetched (via an additional API body expansion) and ac:image captions are extracted and rendered as an italic line directly below the image:

![](image.png)
_Caption text_

When disabled, no caption is added.

• Default: False
• ENV Var: CME_EXPORT__IMAGE_CAPTIONS

export.embed_images¶

Embed images in the Markdown as base64 data URIs (![alt](data:image/png;base64,...)) instead of linking to the downloaded attachment files. Each page becomes self-contained, which helps when feeding pages to an LLM or another tool that only reads the Markdown. Files get much larger. Attachments are still downloaded, and an image falls back to a regular link when its file is not available locally (for example with export.attachments_export=disabled). Also applies with export.attachment_href=wiki.

• Default: False
• ENV Var: CME_EXPORT__EMBED_IMAGES

export.page_breadcrumbs¶

Whether to include breadcrumb links at the top of the page.

• Default: True
• ENV Var: CME_EXPORT__PAGE_BREADCRUMBS

export.table_column_width¶

Controls the visual alignment and space padding of Markdown table columns.

• Default: mixed
• ENV Var: CME_EXPORT__TABLE_COLUMN_WIDTH

export.page_properties_format¶

Controls how Confluence Page Properties macros (key-value tables) are rendered. Duplicate property keys are automatically disambiguated by appending a counter (e.g. status, status_2, status_3).

YAML front matter preserves readable Unicode text (for example, city: Казань) in property values, page labels, and page metadata.

• Default: frontmatter_and_table
• ENV Var: CME_EXPORT__PAGE_PROPERTIES_FORMAT

export.page_properties_report_format¶

Controls how Confluence Page Properties Report macros (dynamic cross-page property tables) are rendered.

• Default: frozen
• ENV Var: CME_EXPORT__PAGE_PROPERTIES_REPORT_FORMAT

export.confluence_url_in_frontmatter¶

Whether to include the original Confluence page URL in the YAML front matter of the exported file.

If a Page Properties macro on the page already defines confluence_webui_url or confluence_tinyui_url, the value from the macro takes precedence over the URL extracted from the API.

• Default: none
• ENV Var: CME_EXPORT__CONFLUENCE_URL_IN_FRONTMATTER

export.page_metadata_in_frontmatter¶

Add eight Confluence page metadata fields to the YAML front matter of each exported page.

Fields with empty or zero values are omitted. If a Page Properties macro on the page already defines a key with the same name, the macro value takes precedence.

confluence_page_id is intentionally written as a quoted string (e.g. '629839369') rather than an integer. Confluence Cloud page IDs can exceed JavaScript's safe-integer range (2^53 − 1), so JS-based static site generators (Hugo, Astro, …) parsing the front matter would silently truncate them. confluence_created and confluence_last_modified are also quoted because PyYAML wraps ISO-8601 timestamps with timezone offsets to prevent loaders from coercing the value into a datetime object.

Example front matter with both confluence_url_in_frontmatter: webui and page_metadata_in_frontmatter: true:

---
tags:
  - team-foo
confluence_webui_url: https://.../wiki/spaces/.../pages/123/Title
confluence_page_id: '123'
confluence_space_key: TEAM
confluence_type: page
confluence_created: "2024-08-15T08:34:12.000+02:00"
confluence_created_by: Sam Creator
confluence_last_modified: "2026-04-12T10:34:00.000+02:00"
confluence_last_modified_by: Alex Johnson
confluence_version: 7
---

• Default: false
• ENV Var: CME_EXPORT__PAGE_METADATA_IN_FRONTMATTER

export.filename_encoding¶

Character mapping for filename encoding.

• Default: Default mappings for forbidden characters.
• ENV Var: CME_EXPORT__FILENAME_ENCODING

export.filename_length¶

Maximum length of filenames.

• Default: 255
• ENV Var: CME_EXPORT__FILENAME_LENGTH

export.filename_lowercase¶

Make all exported paths and filenames lowercase. By default the original casing from Confluence is retained.

• Default: False
• ENV Var: CME_EXPORT__FILENAME_LOWERCASE

export.include_document_title¶

Whether to include the document title in the exported markdown file. If enabled, the title will be added as a top-level heading.

• Default: True
• ENV Var: CME_EXPORT__INCLUDE_DOCUMENT_TITLE

export.include_toc¶

Whether to export the Confluence Table of Contents macro. When enabled, the TOC is converted to markdown. When disabled, the TOC macro is removed from the output.

• Default: True
• ENV Var: CME_EXPORT__INCLUDE_TOC

export.include_macro¶

Controls how Confluence include and excerpt-include macros are rendered. The include macro embeds the full content of another page; excerpt-include embeds a named excerpt from another page.

• Default: inline
• ENV Var: CME_EXPORT__INCLUDE_MACRO

export.enable_jira_enrichment¶

Fetch Jira issue data to enrich Confluence pages. When enabled, Jira issue links include the issue summary. Requires Jira auth to be configured.

• Default: True
• ENV Var: CME_EXPORT__ENABLE_JIRA_ENRICHMENT

export.include_jira_status¶

Append the current Jira issue status to enriched issue links. For example, an issue link is exported as [[TEST-123] Fix login timeout (In Progress)](https://example.atlassian.net/browse/TEST-123). Requires export.enable_jira_enrichment and Jira auth to be configured.

• Default: False
• ENV Var: CME_EXPORT__INCLUDE_JIRA_STATUS

export.comments_export¶

Which comments to export to a sidecar .comments.md file placed next to the exported page file, using the same path stem.

Only open comments are included; resolved comments are skipped. Replies are listed flat below their parent comment. Disabled by default; enabling adds one to two extra API calls per page.

Sidecar example for comments_export = "all":

---
confluence_page_id: '123'
confluence_page_title: "Example Page"
confluence_webui_url: "https://example.atlassian.net/wiki/spaces/TEAM/pages/123"
---

## Inline comments

### export.comment_headings

Whether each comment in a `.comments.md` sidecar gets a `### <excerpt>` heading. The excerpt comes from the commented text (inline comments) or the comment body (page comments), with Markdown links reduced to their text and cut at a word boundary after 60 characters. Set to `false` to list comments under the `## Inline comments` / `## Page comments` sections without individual headings.

- Default: `True`
- ENV Var: `CME_EXPORT__COMMENT_HEADINGS`

### marked excerpt
> marked excerpt

**Alice** · 2026-04-01

Looks good to me.

## Page comments

### Discussion about the rollout

**Bob** · 2026-04-02

Are we shipping this Friday?

The legacy boolean key inline_comments is migrated automatically: true becomes "inline", false becomes "none".

• Default: none
• ENV Var: CME_EXPORT__COMMENTS_EXPORT

export.convert_status_badges¶

Whether to convert Confluence status badge macros to HTML <mark> elements coloured with the badge's background colour. Each lozenge variant maps to an Atlassian design-system pastel:

When disabled, only the badge label text is kept.

• Default: True
• ENV Var: CME_EXPORT__CONVERT_STATUS_BADGES

export.convert_text_highlights¶

Whether to convert Confluence text highlights (<span style="background-color: rgb(...);">) to HTML <mark> elements with a hex color value. When disabled, the highlight span is stripped and only the plain text is kept.

• Default: True
• ENV Var: CME_EXPORT__CONVERT_TEXT_HIGHLIGHTS

export.convert_font_colors¶

Whether to convert Confluence font colors to HTML <font> elements with a hex color value. Handles both inline-style spans (<span style="color: rgb(...);">) and CSS-class-based spans (<span data-colorid="...">) used in the Confluence export view. When disabled, the color span is stripped and only the plain text is kept.

• Default: True
• ENV Var: CME_EXPORT__CONVERT_FONT_COLORS

export.only_homepage_descendants¶

Limit space exports (spaces, orgs) to the space homepage and its descendants. Set to false to also export pages outside the homepage tree, such as additional root pages and their children. Spaces without a homepage are then exported too. While enabled, a warning reports how many pages were skipped.

• Default: True
• ENV Var: CME_EXPORT__ONLY_HOMEPAGE_DESCENDANTS

export.skip_unchanged¶

Skip exporting pages that have not changed since last export. Uses a lockfile to track page versions.

• Default: True
• ENV Var: CME_EXPORT__SKIP_UNCHANGED

export.cleanup_stale¶

After export, delete local files for pages removed from Confluence or whose export path has changed. Renaming or moving a page in Confluence changes its export path, so the file at the previous path is removed along with its .comments.md sidecar. Renaming a parent page also changes the path of every descendant, because {ancestor_titles} is part of the default export.page_path.

The old file is kept when another page now occupies that exact path, and when the old and new paths are the same file on disk. The latter happens on a case-only rename on a case-insensitive filesystem such as the macOS or Windows default.

• Default: True
• ENV Var: CME_EXPORT__CLEANUP_STALE

export.lockfile_name¶

Name of the lock file used to track exported pages.

• Default: confluence-lock.json
• ENV Var: CME_EXPORT__LOCKFILE_NAME

export.existence_check_batch_size¶

Number of page IDs per batch when checking page existence during cleanup. Capped at 25 for self-hosted (CQL).

• Default: 250
• ENV Var: CME_EXPORT__EXISTENCE_CHECK_BATCH_SIZE

connection_config.*¶

connection_config.backoff_and_retry¶

Enable or disable automatic retry with exponential backoff on network errors.

• Default: True
• ENV Var: CME_CONNECTION_CONFIG__BACKOFF_AND_RETRY

connection_config.backoff_factor¶

Multiplier for exponential backoff between retries. For example, 2 means each retry waits twice as long as the previous.

• Default: 2
• ENV Var: CME_CONNECTION_CONFIG__BACKOFF_FACTOR

connection_config.max_backoff_seconds¶

Maximum seconds to wait between retries.

• Default: 60
• ENV Var: CME_CONNECTION_CONFIG__MAX_BACKOFF_SECONDS

connection_config.max_backoff_retries¶

Maximum number of retry attempts before giving up.

• Default: 5
• ENV Var: CME_CONNECTION_CONFIG__MAX_BACKOFF_RETRIES

connection_config.retry_status_codes¶

HTTP status codes that trigger a retry.

• Default: [413, 429, 502, 503, 504]
• ENV Var: CME_CONNECTION_CONFIG__RETRY_STATUS_CODES

connection_config.timeout¶

Timeout in seconds for API requests. Prevents hanging on slow or unresponsive servers.

• Default: 30
• ENV Var: CME_CONNECTION_CONFIG__TIMEOUT

connection_config.verify_ssl¶

Whether to verify SSL certificates for HTTPS requests. Set to False only if you are sure about the security of your connection.

• Default: True
• ENV Var: CME_CONNECTION_CONFIG__VERIFY_SSL

connection_config.ca_bundle¶

Path to a PEM file with the CA certificates used to verify HTTPS connections. Use it for self-hosted instances whose certificates are issued by an internal root or intermediate CA. The file replaces the default certificate bundle, so include any public CAs that are still needed. Ignored when connection_config.verify_ssl is False.

• Default: None
• ENV Var: CME_CONNECTION_CONFIG__CA_BUNDLE

connection_config.use_v2_api¶

Enable Confluence REST API v2 endpoints. Supported on Atlassian Cloud and Data Center 8+. Disable for self-hosted Server instances.

• Default: False
• ENV Var: CME_CONNECTION_CONFIG__USE_V2_API

connection_config.max_workers¶

Maximum number of parallel workers for page export. Set to 1 for serial/debug mode. Higher values improve performance but may hit API rate limits.

• Default: 20
• ENV Var: CME_CONNECTION_CONFIG__MAX_WORKERS