Convert Pages

The page convert commands convert a Confluence page to Markdown and write the result to stdout or a file.

Convert by ID


acp2md page convert by-id PAGE_ID [flags]

The page ID is the number in the Confluence page URL: .../pages/123456/Page+Title.

Examples


# Print Markdown to stdout
acp2md page convert by-id 123456
 
# Save to a file
acp2md page convert by-id 123456 --output page.md
 
# Include metadata header (YAML front matter)
acp2md page convert by-id 123456 --output page.md --include-metadata
 
# Convert a draft version
acp2md page convert by-id 123456 --get-draft
 
# Convert a specific historical version
acp2md page convert by-id 123456 --version 5
 
# Plain text output — strip all formatting (bold, italic, colors)
acp2md page convert by-id 123456 --exclude-marks --output plain.md
 
# Pipe page ID from stdin
echo "123456" | acp2md page convert by-id > page.md

Flags

Flag	Short	Default	Description
`--output`	`-o`	(stdout)	Output file path
`--status`	`-s`	`current`	Page status filter: `current`, `archived`, `trashed`, `deleted`, `draft`
`--version`	`-v`	`-1` (latest)	Convert a specific version number
`--get-draft`	`-d`	`false`	Retrieve the draft (unpublished) version
`--space-key`		(none)	Space key — required for some extension flags (`--ext-render-recently-updated`, `--ext-render-listlabels`)
`--include-labels`	`-l`	`false`	Include page labels in the output
`--include-version`	`-V`	`false`	Include version number in the output
`--include-versions`	`-L`	`false`	Include full version history in the output
`--conflict-resolution`		`overwrite`	How to handle an existing output file: `overwrite`, `skip`, `versioned`
`--sync`		`true`	Track a `.convert-sync-state.json` file alongside the output and skip re-conversion when the page version is unchanged. Deletes the local file if the page is removed from Confluence. Mutually exclusive with `--incremental`. No effect when writing to stdout.
`--incremental`		`false`	Like `--sync`, but keeps the local file if the page is removed from Confluence. Mutually exclusive with `--sync`. No effect when writing to stdout.

Convert by title


acp2md page convert by-title "PAGE TITLE" [flags]

Searches for pages by exact, case-sensitive title and converts the best match. If multiple pages match, the result can be narrowed with --sort.

Examples


# Convert by exact title
acp2md page convert by-title "API Reference" --output api.md
 
# Sort by most recently modified and take the first result
acp2md page convert by-title "Release Notes" --sort -modified-date --output notes.md
 
# Plain text output for LLM ingestion
acp2md page convert by-title "Team Guidelines" --exclude-marks --output guidelines.md
 
# Pipe title from stdin
echo "Project Overview" | acp2md page convert by-title > overview.md

Flags

All flags from by-id apply, plus:

Flag	Short	Default	Description
`--sort`	`-S`	(none)	Sort matching results: `id`, `-id`, `created-date`, `-created-date`, `modified-date`, `-modified-date`, `title`, `-title`

Convert by URL


acp2md page convert by-url URL [flags]

Aliases: url, u

Extracts the page ID from a Confluence URL and converts the page to Markdown. This is convenient when you have a browser URL and want to skip looking up the page ID manually.

Supported URL formats:

https://domain.atlassian.net/wiki/spaces/KEY/pages/123456/Page+Title
https://domain.atlassian.net/wiki/spaces/KEY/pages/123456
https://domain.atlassian.net/wiki/pages/viewpage.action?pageId=123456

Examples


# Convert directly from a Confluence URL
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928/API+Reference"
 
# Save to a file
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" --output api.md
 
# Works with viewpage URLs too
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/pages/viewpage.action?pageId=163928" --output page.md
 
# Plain text output
acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" --exclude-marks --output plain.md
 
# Pipe URL from stdin
echo "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/163928" | acp2md page convert by-url > page.md

Flags

All flags from by-id apply.

Conversion flags

These flags are available on by-id, by-title, and by-url and control what is included in the Markdown output.

Content & metadata

Flag	Short	Default	Description
`--include-metadata`	`-m`	`true`	Add a YAML front matter block (title, author, created/modified dates)
`--exclude-marks`	`-x`	`false`	Strip all inline formatting: bold, italic, underline, colours, background colours. Useful for plain-text pipelines and LLM ingestion

Images & media

Flag	Short	Default	Description
`--embed-images`	`-e`	`true`	Embed images as base64 data URIs (increases file size)
`--ext-embed-drawio`	`-D`	`true`	Embed draw.io diagrams as base64 images
`--ext-embed-roadmap`		`true`	Embed Roadmap Planner diagrams as base64 images
`--embed-media-images`		`true`	Embed Confluence media files (avatars, inline images) as base64 data URIs

Pass --embed-images=false to keep image references as external URLs instead of embedding them inline.

Extension flags

Flag	Default	Description
`--ext-render-toc`	`true`	Generate a Markdown table of contents from the document headings
`--ext-render-recently-updated`	`true`	Render the recently-updated macro as a Markdown list (requires `--space-key`)
`--ext-render-listlabels`	`true`	Render label badges (requires `--space-key`)
`--ext-render-pagetree`	`true`	Render the pagetree macro as a nested Markdown list
`--ext-render-children`	`true`	Render the children macro as a flat Markdown list
`--ext-render-contributors`	`true`	Render the contributors macro as a Markdown list
`--ext-render-page-signatures`	`true`	Render Document Control signature tables
`--ext-render-qc-properties`	`true`	Render QC property and revision macros with their actual values
`--ext-render-task-report`	`true`	Render the tasks-report-macro as a Markdown table (requires Confluence credentials)
`--ext-render-content-report`	`true`	Render the content-report-table macro as a Markdown table (requires Confluence credentials)
`--ext-resolve-inline-card-titles`	`true`	Resolve inline Confluence card links to their actual page titles

Output conflict resolution

When writing to a file with --output, the --conflict-resolution flag controls what happens if the file already exists:

Value	Behaviour
`overwrite`	Replace the existing file (default)
`skip`	Leave the existing file untouched and skip conversion
`versioned`	Append the Confluence version number: `page-v5.md`

Metadata header

When --include-metadata is enabled (the default), a YAML front matter block is prepended to the output:


---
Title: Getting Started Guide
AuthorID: 5a1b2c3d4e5f6a7b8c9d0e1f
CreatedAt: 2024-01-15 10:30:00
ID: 123456789
LastOwnerID:
OwnerID: 5a1b2c3d4e5f6a7b8c9d0e1f
ParentID: 987654321
ParentType: page
Position: 424489544
SpaceID: 278077
Status: current
SubType:
VersionAuthorID: 5a1b2c3d4e5f6a7b8c9d0e1f
VersionCreatedAt: 2024-03-10 14:22:00
VersionMessage:
VersionMinorEdit: false
VersionNumber: 6
---
 
# Getting Started Guide
...

The metadata block includes:

Title — the page title as it appears in Confluence
AuthorID / OwnerID — Confluence account IDs for the original author and current owner
CreatedAt / VersionCreatedAt — when the page was created and when the current version was last modified
ID / SpaceID / ParentID — Confluence identifiers for the page, space, and parent page
Status — page status (current, archived, trashed, deleted, draft)
VersionNumber — the current version number of the page

This is useful for static site generators, migration tracking, content inventory, and audit workflows.

Practical examples

Export a page for a static site


acp2md page convert by-id 123456 \
  --include-metadata \
  --output docs/my-page.mdx

Build a RAG knowledge base


acp2md page convert by-id 123456 \
  --exclude-marks \
  --embed-images=false \
  --output rag/123456.md

Archive a draft before publishing


acp2md page convert by-id 123456 \
  --get-draft \
  --output archive/draft-123456.md

Refresh a governed export efficiently


acp2md page convert by-id 123456 \
  --output exports/page.md \
  --sync

CI/CD pipeline


export ACP2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACP2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACP2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN
 
acp2md page convert by-id "$PAGE_ID" --output "docs/$PAGE_ID.md"