Claude-skill-registry-data 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.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/markdown-confluence-sync" ~/.claude/skills/majiayu000-claude-skill-registry-data-markdown-confluence-sync && rm -rf "$T"

manifest: data/markdown-confluence-sync/SKILL.md

source content

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