Markdown Confluence Sync

markdown-confluence-sync

Sync markdown projects to Confluence using the markdown_confluence tool. Use for publishing, crawling, and managing Confluence pages from local markdown files.

majiayu000/claude-skill-registry-data·0installs23stars

SKILL.md

Full skill instructions

Markdown Confluence Sync

Synchronize local markdown projects with Confluence using the markdown-confluence CLI tool.

Tool Location

/Users/tylerstapler/Documents/personal-wiki/tools/markdown_confluence/.venv/bin/markdown-confluence

Quick Reference

Environment Variables (Required for Authentication)

export CONFLUENCE_BASE_URL="https://betfanatics.atlassian.net"
export ATLASSIAN_USER_NAME="[email protected]"
# ATLASSIAN_API_TOKEN must be set (retrieved from keychain/secrets)

Core Commands

Command	Purpose
`publish`	Upload markdown to Confluence
`crawl page`	Download a single Confluence page
`crawl page-tree`	Download page and descendants
`handle-deleted`	Manage deleted local files
`validate-links`	Check broken links

Publishing Workflow

1. Setup Configuration

Create .markdown-confluence.json in your project:

{
  "confluence": {
    "base_url": "https://betfanatics.atlassian.net",
    "parent_id": "PARENT_PAGE_ID",
    "username": "[email protected]"
  },
  "publish": {
    "folder_to_publish": ".",
    "frontmatter_from_document_start": true,
    "resolve_relative_links": true,
    "respect_link_dependencies": true
  }
}

2. Add Frontmatter to Markdown Files

---
connie-title: "Custom Page Title"
connie-page-id: "123456"        # Existing page ID (auto-added after first publish)
connie-parent-id: "789012"      # Override parent page
connie-publish: true            # Set false to skip
---

# Your Content Here

3. Publish Commands

# Always dry-run first
CONFLUENCE_BASE_URL="https://betfanatics.atlassian.net" \
ATLASSIAN_USER_NAME="[email protected]" \
/Users/tylerstapler/Documents/personal-wiki/tools/markdown_confluence/.venv/bin/markdown-confluence \
publish . --config .markdown-confluence.json --dry-run --verbose

# Actual publish
/Users/tylerstapler/Documents/personal-wiki/tools/markdown_confluence/.venv/bin/markdown-confluence \
publish . --config .markdown-confluence.json --verbose

# Force update unchanged content
publish . --config .markdown-confluence.json --force

# Stop on first error
publish . --config .markdown-confluence.json --fail-fast

Crawling Confluence

Download Single Page

CONFLUENCE_BASE_URL="https://betfanatics.atlassian.net" \
ATLASSIAN_USER_NAME="[email protected]" \
/Users/tylerstapler/Documents/personal-wiki/tools/markdown_confluence/.venv/bin/markdown-confluence \
crawl page PAGE_ID_OR_URL --output ./output_dir --verbose

Download Page Tree

markdown-confluence crawl page-tree PAGE_ID --output ./output_dir --max-depth 3 --verbose

Key Publish Options

Option	Description
`--dry-run`	Preview without publishing
`--verbose` / `-v`	Increase output detail
`--force`	Force update unchanged pages
`--fail-fast`	Stop on first error
`--delete-archived`	Delete archived pages
`--force-hierarchy`	Use directory structure for hierarchy
`--update-frontmatter`	Update frontmatter with corrected IDs
`--pattern "*/.md"`	Filter files to publish
`--exclude "/draft/"`	Exclude patterns

Frontmatter Fields

Field	Purpose
`connie-title`	Custom page title
`connie-page-id`	Existing page ID (for updates)
`connie-parent-id`	Parent page ID
`connie-parent-page-id`	Alternative parent field
`connie-publish`	Enable/disable publishing
`connie-skip-link-resolution`	Skip link resolution

Common Workflows

New Project Setup

Create project directory with markdown files
Create .markdown-confluence.json with parent page ID
Run --dry-run to verify structure
Publish - frontmatter will be auto-updated with page IDs

Update Existing Project

Edit markdown files
Run publish (tool detects changes via hashing)
Use --force if content unchanged but needs update

Troubleshooting

400 Bad Request: Parent page may have corrupted format
Duplicate title: Add unique connie-title in frontmatter
Page not found: Page ID invalid, tool will auto-create new page
Archived pages: Use --delete-archived to recreate

Features

Mermaid diagram rendering
Wikilink support ([[page]] and [[page|title]])
Relative link resolution between markdown files
Directory hierarchy to page hierarchy mapping
Asset/image handling
Content hashing for efficient updates

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/majiayu000/claude-skill-registry-data --skill markdown-confluence-sync

View on GitHub

data/markdown-confluence-sync/SKILL.md