create-confluence-sync

Bidirectional documentation sync between local files and Confluence Server via Git.

Edit XHTML files locally, commit — changes sync to Confluence automatically. Someone edits in Confluence — changes sync back on your next commit.

Quick Start

npx create-confluence-sync

The wizard will ask for:

• Confluence URL
• Personal Access Token (skipped when CONFLUENCE_PERSONAL_TOKEN is set)
• Space to sync

It downloads all pages, sets up Git with auto-sync hooks, and you're ready.

Non-interactive: npx create-confluence-sync --url <url> --space <KEY> --yes [--token <token>].

Token

The token is read from the CONFLUENCE_PERSONAL_TOKEN environment variable first, then from token in .confluence/config.json. When the variable is set during setup, the token is not written to config.json at all.

The hook, sync and restore check the token before doing anything and stop if it is expired (Confluence Server answers such requests as an anonymous user). Check it by hand with npx create-confluence-sync check.

How It Works

1. You edit .xhtml files in docs/ folder
2. You git commit
3. Post-commit hook automatically:
   • Validates every page in the commit and the token — before any change in Confluence
   • Pulls changes from Confluence
   • Merges with your changes
   • Wraps flat files into folders and pushes your changes, parents before children
   • Updates the local tree map

If validation or push fails, the commit is rolled back and your changes stay staged.

Page Hierarchy

A page with children is a folder with a same-named .xhtml file inside. A leaf page may be a flat Page.xhtml in its parent folder — sync moves it into Page/Page.xhtml on commit. A whole new subtree can be committed at once.

The push is blocked, with a list of files and reasons, when:

• a file contains <?xml ?>, <!DOCTYPE>, <html>/<head>/<body>, xmlns declarations or merge conflict markers (CDATA macro bodies are not checked);
• a new page title is already taken in the space, or used twice in the commit;
• a title contains < > : " / \ | ? *, ends with a space or a dot, or is longer than 100 characters;
• a new page sits in a folder that has no page file of its own (it would otherwise land at the space root).

File Structure

After setup:

your-project/
├── docs/
│   └── LLS/                    # your Confluence space
│       ├── Page Title/
│       │   ├── Page Title.xhtml
│       │   └── Child Page/
│       │       └── Child Page.xhtml
├── .confluence/
│   ├── config.json             # connection settings (gitignored)
│   └── tree.json               # page map (tracked in git)
├── AGENTS.md                   # instructions for AI agents
└── .gitignore

Commands

# Setup (first time)
npx create-confluence-sync

# Manual sync
npx create-confluence-sync sync

# Push specific file
npx create-confluence-sync sync "docs/LLS/Page/Page.xhtml"

# Restore hidden pages (interactive)
npx create-confluence-sync restore

# Restore by name
npx create-confluence-sync restore "Page Title"

# List spaces
npx create-confluence-sync spaces

# Get page content
npx create-confluence-sync page <pageId>

# View remote tree
npx create-confluence-sync tree

# View local tree
npx create-confluence-sync local-tree

# Delete page from Confluence
npx create-confluence-sync delete <pageId>

# Move page under another parent in Confluence
npx create-confluence-sync move <pageId> <newParentId>

# Check token and connection
npx create-confluence-sync check

# Wrap flat files into folders and validate pages, without network (--dry-run: only report)
npx create-confluence-sync normalize [--dry-run]

# Regenerate AGENTS.md (e.g. after updating the package)
npx create-confluence-sync agents-md

Development

npm test          # unit tests, no network
npm run test:e2e  # end-to-end against a real Confluence, see tests/data.example.json

Hiding Pages (Virtual Delete)

Delete a file or folder locally and commit. The page stays in Confluence but stops syncing locally. Use restore to bring it back.

Format

Files use Confluence Storage Format (XHTML):

<h2>Title</h2>
<p>Text with <strong>bold</strong> and <em>italic</em>.</p>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

AI Agent Compatible

The generated AGENTS.md file contains full instructions for AI agents (Claude, GPT, etc.) to create, edit, and manage documentation through the same Git workflow.

Requirements

• Node.js 20+
• Git
• Confluence Server with REST API access
• Personal Access Token

License

MIT