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.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

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.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.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.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).

• 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.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

### 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.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.

• 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.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