@aashari/nodejs-confluence-export

Confluence Export CLI

A powerful Node.js/TypeScript command-line tool for exporting Confluence pages with advanced filtering capabilities, preserving page relationships and content formatting.

Overview

This CLI tool enables you to export entire Confluence spaces to your local filesystem while maintaining hierarchical structure and page relationships. It converts Confluence's complex storage format into clean Markdown or HTML files with proper formatting for macros, tables, code blocks, and other Confluence elements.

Key Features

• Complete Space Export: Export an entire Confluence space with a single command
• Hierarchical Organization: Preserves page ancestry and relationships in folder structure
• Flexible Filtering: Exclude specific pages or entire branches with parent-based or title pattern filters
• Content Preservation: Properly renders Confluence macros, tables, code blocks, info/note panels, and more
• Metadata Retention: Includes page metadata (created date, updated date, path/breadcrumbs) in exports
• Progress Indicators: Shows real-time progress during export with clear summaries

Getting Started

Prerequisites

• Node.js (>=18.x): Download
• Confluence Cloud Account with API access

Step 1: Get Your Atlassian API Token

• Go to your Atlassian API token management page: https://id.atlassian.com/manage-profile/security/api-tokens
• Click Create API token.
• Give it a descriptive Label (e.g., confluence-export-cli).
• Click Create.
• Copy the generated API token immediately. You won't be able to see it again.

Step 2: Configure Credentials

Method A: Environment Variables

Set these environment variables:

export ATLASSIAN_SITE_NAME="yourcompany"        # For yourcompany.atlassian.net
export ATLASSIAN_USER_EMAIL="[e-mail]"
export ATLASSIAN_API_TOKEN="your-api-token"

Method B: .env File

Create a .env file in your project directory:

ATLASSIAN_SITE_NAME=yourcompany
ATLASSIAN_USER_EMAIL=[e-mail]
ATLASSIAN_API_TOKEN=your-api-token

Usage Examples

Quick Use with npx

Export a space to the default output directory (./output):

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY

Using inline environment variables:

ATLASSIAN_SITE_NAME=yourcompany ATLASSIAN_USER_EMAIL=[e-mail] ATLASSIAN_API_TOKEN=your-api-token npx -y @aashari/nodejs-confluence-export export --space SPACEKEY

Install Globally

npm install -g @aashari/nodejs-confluence-export

Then run directly:

confluence-export export --space SPACEKEY

Custom Output Directory

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY --output-dir ./my-exports

Choose Format (Markdown or HTML)

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY --format html

Filter Pages to Exclude

Exclude a specific page and all its children:

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY --ignore parent:12345678

Exclude pages matching a title pattern:

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY --ignore title:DRAFT

Use multiple filters:

npx -y @aashari/nodejs-confluence-export export --space SPACEKEY --ignore parent:12345678 --ignore title:"Internal Only"

Command Reference

Main Commands

confluence-export export [options]  Export Confluence pages from a specified space

Export Options

• -s, --space <spaceKey>: (Required) The key of the Confluence space to export
• -o, --output-dir <path>: Directory to save exported files (default: ./output)
• -f, --format <format>: Export format - markdown or html (default: markdown)
• --ignore <filter...>: Pages to ignore. Format: "parent:ID" to ignore a page and all children, or "title:REGEX" to ignore pages matching regex pattern. Can be used multiple times.

Output Structure

The exported content will be organized as follows:

output/
├── space-name/
│   ├── page-title-1/
│   │   ├── child-page-1.md
│   │   └── child-page-2.md
│   ├── page-title-2/
│   │   └── ...
│   └── ...
└── ...

Each Markdown/HTML file includes:

• Title as heading
• Metadata section with:
  • Path/breadcrumbs
  • Created date
  • Updated date
• Page content with properly rendered Confluence elements
• Footer with export timestamp

Troubleshooting

If you encounter issues with the export:

• Verify your Atlassian credentials are correct
• Ensure you have appropriate permissions for the space
• Check for rate limiting if exporting large spaces
• Use the DEBUG=true environment variable for detailed logs:

DEBUG=true npx -y @aashari/nodejs-confluence-export export --space SPACEKEY

Development

• Build: npm run build
• Test: npm test
• Format code: npm run format
• Lint code: npm run lint

License

ISC