What is markdown-confluence-sync?

The Markdown Confluence Sync skill provides a powerful bridge between local development environments and Confluence, allowing users to synchronize Markdown-based documentation projects seamlessly. It automates the publishing process, handles complex page hierarchies, and ensures content consistency with features like link resolution, Mermaid diagram rendering, and asset management, making it an essential tool for maintaining a high-quality, automated knowledge base.

When should I use markdown-confluence-sync?

markdown-confluence-sync is useful in the following scenarios: • Automated Documentation Publishing: Synchronize technical documentation directly from a local Git repository to Confluence, ensuring that the internal wiki is always in sync with the latest code changes. • Content Migration and Backup: Use the crawl functionality to download entire Confluence page trees into local Markdown files for offline editing, version control, or platform migration. • Technical Writing Workflow: Author documentation in preferred Markdown editors using Wikilinks and Mermaid diagrams, then automatically convert and upload them to Confluence without manual formatting. • Large-Scale Wiki Management: Manage complex directory structures and page hierarchies automatically using the tool's ability to map local folders to Confluence parent-child page relationships.

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

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="tyler.stapler@betfanatics.com"
# 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": "tyler.stapler@betfanatics.com"
  },
  "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="tyler.stapler@betfanatics.com" \
/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="tyler.stapler@betfanatics.com" \
/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

markdown-confluence-sync

When & Why to Use This Skill

Use Cases