# Confluence Sync
A Python tool to synchronize Confluence pages with local markdown files using version control to prevent conflicts.
## Features
- **Pull**: Download Confluence pages as markdown files to your local directory
- **Push**: Upload local markdown changes back to Confluence with version conflict detection
- **Status**: See which files have been modified locally or remotely
- **Version Control**: Prevents overwriting remote changes by checking page versions before pushing
## Installation
This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
```bash
# Clone the repository
git clone <repository-url>
cd confluence-sync
# Install dependencies
uv sync
# Install the CLI tool
uv pip install -e .
```
## Configuration
Create a configuration file using:
```bash
confluence-sync init
```
This creates a `confluence-sync.yml` file. Edit it with your Confluence details:
```yaml
confluence:
url: "https://your-domain.atlassian.net"
username: "your-email@domain.com"
api_token: "your-api-token"
space_key: "YOUR_SPACE_KEY"
local_path: "docs"
ignore_patterns:
- "*.tmp"
- ".git/*"
```
### Getting an API Token
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a label and copy the token
4. Use your email and the token for authentication
## Usage
### Pull pages from Confluence
```bash
confluence-sync pull
```
This downloads all pages from the specified space as markdown files.
### Check status
```bash
confluence-sync status
```
Shows which files are new, modified, or deleted locally.
### Push local changes
```bash
# Push all tracked files
confluence-sync push
# Push specific files
confluence-sync push docs/page1.md docs/page2.md
```
The push command will:
- Check for version conflicts before uploading
- Block the push if remote pages have been modified
- Show which files couldn't be pushed due to conflicts
### File Format
Each markdown file includes metadata in the header:
```markdown
---
confluence_id: 123456789
confluence_title: My Page Title
confluence_version: 5
confluence_parent_id: 987654321
confluence_space_key: MYSPACE
---
# Page Content
Your markdown content here...
```
## Version Control Workflow
1. **Pull** to get the latest pages from Confluence
2. **Edit** markdown files locally
3. **Status** to see what's changed
4. **Push** to upload changes
5. If there are conflicts, **pull** again to merge remote changes
## Project Structure
```
confluence-sync/
├── src/confluence_sync/
│ ├── __init__.py
│ ├── cli.py # Command-line interface
│ ├── config.py # Configuration management
│ ├── confluence_client.py # Confluence API wrapper
│ └── sync.py # Main sync logic
├── pyproject.toml # Project configuration
└── README.md
```
Raw data
{
"_id": null,
"home_page": null,
"name": "confluence-sync",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "confluence, markdown, sync, documentation, atlassian",
"author": "shouhanzen",
"author_email": "shouhanzen <shouhanzen@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9c/fd/0315ad18645fc9706fae4988a5d60c8979f7d5db22f4d58e9d06850b231d/confluence_sync-0.1.0.tar.gz",
"platform": null,
"description": "# Confluence Sync\n\nA Python tool to synchronize Confluence pages with local markdown files using version control to prevent conflicts.\n\n## Features\n\n- **Pull**: Download Confluence pages as markdown files to your local directory\n- **Push**: Upload local markdown changes back to Confluence with version conflict detection\n- **Status**: See which files have been modified locally or remotely\n- **Version Control**: Prevents overwriting remote changes by checking page versions before pushing\n\n## Installation\n\nThis project uses [uv](https://github.com/astral-sh/uv) for dependency management.\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd confluence-sync\n\n# Install dependencies\nuv sync\n\n# Install the CLI tool\nuv pip install -e .\n```\n\n## Configuration\n\nCreate a configuration file using:\n\n```bash\nconfluence-sync init\n```\n\nThis creates a `confluence-sync.yml` file. Edit it with your Confluence details:\n\n```yaml\nconfluence:\n url: \"https://your-domain.atlassian.net\"\n username: \"your-email@domain.com\"\n api_token: \"your-api-token\"\n space_key: \"YOUR_SPACE_KEY\"\nlocal_path: \"docs\"\nignore_patterns:\n - \"*.tmp\"\n - \".git/*\"\n```\n\n### Getting an API Token\n\n1. Go to https://id.atlassian.com/manage-profile/security/api-tokens\n2. Click \"Create API token\"\n3. Give it a label and copy the token\n4. Use your email and the token for authentication\n\n## Usage\n\n### Pull pages from Confluence\n\n```bash\nconfluence-sync pull\n```\n\nThis downloads all pages from the specified space as markdown files.\n\n### Check status\n\n```bash\nconfluence-sync status\n```\n\nShows which files are new, modified, or deleted locally.\n\n### Push local changes\n\n```bash\n# Push all tracked files\nconfluence-sync push\n\n# Push specific files\nconfluence-sync push docs/page1.md docs/page2.md\n```\n\nThe push command will:\n- Check for version conflicts before uploading\n- Block the push if remote pages have been modified\n- Show which files couldn't be pushed due to conflicts\n\n### File Format\n\nEach markdown file includes metadata in the header:\n\n```markdown\n---\nconfluence_id: 123456789\nconfluence_title: My Page Title\nconfluence_version: 5\nconfluence_parent_id: 987654321\nconfluence_space_key: MYSPACE\n---\n\n# Page Content\n\nYour markdown content here...\n```\n\n## Version Control Workflow\n\n1. **Pull** to get the latest pages from Confluence\n2. **Edit** markdown files locally\n3. **Status** to see what's changed\n4. **Push** to upload changes\n5. If there are conflicts, **pull** again to merge remote changes\n\n## Project Structure\n\n```\nconfluence-sync/\n\u251c\u2500\u2500 src/confluence_sync/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 confluence_client.py # Confluence API wrapper\n\u2502 \u2514\u2500\u2500 sync.py # Main sync logic\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tool to sync Confluence pages with local markdown files using version control",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/shouhanzen/confluence-sync",
"Issues": "https://github.com/shouhanzen/confluence-sync/issues",
"Repository": "https://github.com/shouhanzen/confluence-sync"
},
"split_keywords": [
"confluence",
" markdown",
" sync",
" documentation",
" atlassian"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be1c5a36eb0c71ed0e013aa2a5f8858d758a659a8d3a368d8988ffee85c6134e",
"md5": "532697c6627c311f5a8434b55be1a3be",
"sha256": "995c55f0cdc4f55e6d6eeee6e7921a783db3cccbb2550f8791fae48efadda303"
},
"downloads": -1,
"filename": "confluence_sync-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "532697c6627c311f5a8434b55be1a3be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12418,
"upload_time": "2025-09-09T01:32:55",
"upload_time_iso_8601": "2025-09-09T01:32:55.941598Z",
"url": "https://files.pythonhosted.org/packages/be/1c/5a36eb0c71ed0e013aa2a5f8858d758a659a8d3a368d8988ffee85c6134e/confluence_sync-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9cfd0315ad18645fc9706fae4988a5d60c8979f7d5db22f4d58e9d06850b231d",
"md5": "5562f5f55a58fe122597c8612611ccef",
"sha256": "b7543db7aec05c7ac01d28d39331ab7e52c0c992486c21bdc1f4905fd54a6be0"
},
"downloads": -1,
"filename": "confluence_sync-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5562f5f55a58fe122597c8612611ccef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9894,
"upload_time": "2025-09-09T01:32:57",
"upload_time_iso_8601": "2025-09-09T01:32:57.090956Z",
"url": "https://files.pythonhosted.org/packages/9c/fd/0315ad18645fc9706fae4988a5d60c8979f7d5db22f4d58e9d06850b231d/confluence_sync-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 01:32:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shouhanzen",
"github_project": "confluence-sync",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "confluence-sync"
}
JSON
