archon-confluence-import

CLI companion for the archon-confluence Premium plugin in ArchON — a visual C4 architecture tool.

The archon-confluence plugin (available in the ArchON Plugins Marketplace) lets you build a hierarchy of Confluence pages, compose content with a rich editor, and export everything as a ZIP archive. This CLI tool takes that ZIP and imports the full page hierarchy with all content and media attachments into your Atlassian Confluence instance.

Features

• Confluence Server / Data Center / Cloud — auto-detects API version (v1 storage format for Server/DC, v2 ADF for Cloud)
• ADF to Storage Format conversion — automatically converts Atlassian Document Format to Confluence Storage Format (XHTML) for Server/DC instances
• Full page hierarchy — creates nested pages preserving parent-child relationships
• Media attachments — uploads images (PNG), videos (MP4), and all referenced files as page attachments
• Confluence layouts — converts ac:layout / ac:layout-section / ac:layout-cell structures
• Smart archiving — existing pages under the target parent are moved to a ~Archive folder before import
• Page recycling — reuses archived pages when available instead of creating duplicates
• Attachment cleanup — purges old attachments from archived pages to prevent filename conflicts
• Export code conflict resolution — if a page title conflicts space-wide, retries with [ExportCode] Title and (N) suffix

Install

npm install -g archon-confluence-import

Usage

Via CLI flags

archon-confluence-import \
  --url https://confluence.company.com \
  --user [email protected] \
  --password YOUR_API_TOKEN \
  --space ARCH \
  --parent 12345678 \
  export.zip

Via environment variables

export CONFLUENCE_URL=https://confluence.company.com
export [email protected]
export CONFLUENCE_USER_PASSWORD=YOUR_API_TOKEN
export CONFLUENCE_SPACE_ID=ARCH
export CONFLUENCE_PAGE_ID=12345678

archon-confluence-import export.zip

Run directly from build

node build/index.js --url ... --space ... export.zip

Options

| Flag | Env Variable | Description | |------|-------------|-------------| | --url | CONFLUENCE_URL | Confluence base URL (e.g. https://confluence.company.com) | | --user | CONFLUENCE_USER | Username or email for authentication | | --password | CONFLUENCE_USER_PASSWORD | API token (Cloud) or password (Server/DC) | | --space | CONFLUENCE_SPACE_ID | Confluence space key | | --parent | CONFLUENCE_PAGE_ID | Parent page ID — new pages become children of this page | | --verbose | — | Enable detailed logging | | --help | — | Show help message | | --version | — | Show version |

How it works

1. Parse — Reads the ZIP archive and parses export.json (page hierarchy, ADF content, attachment references)
2. Archive — Recursively collects all existing descendant pages under --parent and moves them to ~Archive (renamed to ~{pageId}, body and attachments cleared)
3. Create pages — Walks the hierarchy level by level (parents first). For each page:
   • Checks ~Archive for a recyclable page with the same title
   • If found, moves it back to the correct parent and updates content
   • If not found, creates a new page
   • On title conflict: retries with [ExportCode] Title, then [ExportCode] Title (N)
4. Upload attachments — Uploads all referenced media files (images, PNGs, MP4s) as Confluence page attachments
5. Report — Prints summary with pages created, recycled, archived, and attachments uploaded

Supported content

• Paragraphs, headings (h1–h6), text formatting (bold, italic, underline, strikethrough, code)
• Text color and background color
• Text alignment (left, center, right)
• Bullet lists, ordered lists, nested lists
• Tables with colspan/rowspan, header rows and columns
• Code blocks with language syntax
• Links (external URLs and page anchors)
• Info/Note/Warning/Tip/Error panels
• Blockquotes
• Horizontal rules
• Confluence layouts (single, two-column, three-column, sidebar variants)
• Images and videos as attachments (ac:image, ac:structured-macro for multimedia)
• Children pages macro
• Expand macro

Build from source

npm install
npm run build

Output: build/index.js — a single minified ESM bundle with Node.js shebang.

Publish

npm run build
npm publish

The prepublishOnly script runs the build automatically before publishing. Only the build/ directory, README.md, and LICENSE are included in the published package.

License

MIT