Export Confluence Pages to Markdown from the CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

To export Confluence to Markdown from the command line, run atlassian-cli confluence page get <id> --format markdown and redirect the output to a file. markdown is a built-in output format, so one page becomes one clean .md file with no plugins, no copy-paste, and no PDF-to-text cleanup. Scale that single command across a space and you have every Confluence page mirrored as version-controllable text you can commit to Git.

This post is about the export direction: getting content out of Confluence and into Markdown files that live next to your code. If you want the reverse (writing Markdown and publishing it into Confluence), see the sibling guide on Markdown to Confluence and the broader docs-as-code with Confluence workflow.

Export Confluence to Markdown: the one-liner

Every atlassian-cli command accepts a global --format flag, and markdown is one of its supported values (alongside table, json, csv, yaml, and quiet). For a Confluence page, that means the tool renders the page body as Markdown and prints it to standard output:

# Export a single page to a Markdown file
atlassian-cli confluence page get 12345 --format markdown > architecture.md

The result is ordinary Markdown: # headings, bullet and numbered lists, links, tables, and fenced code blocks. Because it is plain text, you can open it in any editor, preview it in your IDE, or pipe it straight into another tool. There is nothing Confluence-specific left to strip out, which is the whole reason to prefer Markdown over the built-in PDF or Word export when your goal is a file you can read and diff.

Add a --profile when you manage more than one Atlassian site so the export runs against the right instance:

# Export from a named profile
atlassian-cli confluence page get 12345 --format markdown --profile prod > architecture.md

Finding the page id

The one thing page get needs is the numeric page id. If you do not have it handy, list the pages in a space or search for the title first:

# List pages in a space (id shows in the output)
atlassian-cli confluence page list --space DEV --limit 50

# Or search by title within a space
atlassian-cli confluence search in-space DEV "architecture"

Prefer machine-readable output when you plan to script the next step. Asking for JSON exposes each page's id and title, which you can slice with jq:

# Get just the page ids in a space
atlassian-cli confluence page list --space DEV --format json | jq -r '.[].id'

Export an entire space to Markdown

A single page is a warm-up. The real request behind "export Confluence to Markdown" is usually "give me the whole space as files I can commit." Combine page list --format json with a shell loop that calls page get --format markdown once per page and names each file after its title:

#!/usr/bin/env bash
# Export every page in a Confluence space to individual Markdown files
set -euo pipefail

SPACE="DEV"
OUT="docs/confluence"
mkdir -p "$OUT"

atlassian-cli confluence page list --space "$SPACE" --format json \
  | jq -r '.[] | [.id, .title] | @tsv' \
  | while IFS=$'\t' read -r id title; do
      # Turn the page title into a filesystem-safe slug
      slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
      echo "Exporting $id -> $OUT/$slug.md"
      atlassian-cli confluence page get "$id" --format markdown > "$OUT/$slug.md"
    done

Run it once and docs/confluence/ fills with one Markdown file per page: getting-started.md, architecture.md, runbook-oncall.md, and so on. The loop is idempotent in the sense that matters for version control: re-exporting a page whose content has not changed produces the same Markdown, so a second run leaves your working tree clean unless something actually changed in Confluence.

Put the export under version control

Once the space lives as Markdown in a folder, it behaves like any other source directory. Commit it and you have a point-in-time snapshot of Confluence in Git history:

# Snapshot the exported space in Git
git add docs/confluence
git commit -m "docs: snapshot Confluence space DEV as markdown"

This is where Markdown export earns its keep. A PDF or Word download is opaque to git diff, but a Markdown file changes line by line. Re-run the export after someone edits a page and the diff shows exactly which paragraphs moved, which links were added, and which sections were deleted. Reviewers can comment on those changes in a pull request. You get a searchable, blameable, revertible record of your documentation, which is the foundation of any docs-as-code practice.

Practical reasons teams pull Confluence into Git as Markdown:

• Migration. Leaving Confluence, or moving a space to a static-site generator, is far easier when the content is already Markdown.
• Offline archive. A committed snapshot survives even if a space is later deleted or archived.
• Review workflows. Route documentation edits through the same pull-request process as code.
• Search and grep. grep across a folder of .md files is faster and more precise than the Confluence search box.

Export approaches compared

Confluence gives you several ways to get content out. They are not interchangeable: the right one depends on whether you want something human-readable and diffable, or a complete structured backup.

For a docs-as-code workflow, the first row is what you want. The JSON export in the second row is complementary rather than competing: use it when you need a faithful backup that preserves metadata the Markdown body does not carry.

Attachments and full-fidelity backups

The --format markdown output is the page body as text. Binary attachments and embedded images are stored separately in Confluence, so they are not inlined into the Markdown file. Pull those with the attachment commands when you need them alongside the text:

# List and download a page's attachments
atlassian-cli confluence attachment list 12345
atlassian-cli confluence attachment download --output ./diagram.png 11111

If your goal is a complete, restorable snapshot rather than readable text, run the structured bulk export next to your Markdown. It captures labels, versions, and metadata that a flattened Markdown body drops:

# Full structured snapshot of a whole space
atlassian-cli confluence bulk export --cql "space = DEV" \
  --output confluence-DEV-backup.json \
  --format json

A common pattern is to keep both: Markdown files for humans and diffs, and a timestamped JSON export for disaster recovery. The Confluence backup runbook wraps that into a scheduled job with retention.

Automate it and round-trip changes

The export loop is a natural fit for CI or a cron job. Run it on a schedule so your Git mirror of Confluence never drifts more than a day behind, and the commit history doubles as an audit log of who changed what and when. Because unchanged pages produce byte-identical Markdown, a scheduled run only creates a commit when something actually changed.

Export is one half of a round-trip. Teams that adopt docs-as-code eventually want to edit the Markdown in Git and push it back into Confluence so non-technical readers still get the wiki view. That reverse pipeline (Markdown to Confluence storage format, then create or update pages) is documented in the Confluence Markdown sync runbook, which uses the same --format markdown flag to pull pages back out for verification. Between the two, you can pick Git or Confluence as your source of truth and keep the other side automatically in step.

For the full list of Confluence subcommands and flags used here, check the command reference, or start from the Confluence CLI hub for an overview of pages, spaces, search, and bulk operations.

FAQ

Related Resources