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
• Space to sync

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

How It Works

1. You edit .xhtml files in docs/ folder
2. You git commit
3. Post-commit hook automatically:
   • Pulls changes from Confluence
   • Merges with your changes
   • Pushes your changes to Confluence
   • Updates the local tree map

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>

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