sync-confluence

Sync Confluence Skill

This skill syncs Markdown documentation from docs/engineering/ to Confluence Cloud using the mark tool. It operates in two distinct modes.

---

Mode A — Scaffold (run once, locally)

Triggered when docs/engineering/ does not exist. Run this once before any CI sync.

Step A1 — Verify prerequisites

Ensure mark is installed:

mark --version

If not installed: brew install mark or go install github.com/kovetskiy/mark@latest.

Step A2 — Create directory structure

Creates the full tree with INDEX.md stubs:

docs/engineering/
├── INDEX.md
├── adr/
│   └── INDEX.md
├── rfc/
│   └── INDEX.md
└── architecture/
    ├── INDEX.md
    └── resources/

Step A3 — Add sample documents

Creates one example ADR and one example RFC using the templates so engineers have a concrete reference to copy from.

Step A4 — Output instructions

After scaffolding, output:

Scaffold complete. Next steps:

1. Review and commit the new directory structure
2. Add mark metadata headers to your documents
3. Configure CONFLUENCE_* secrets in your CI environment
4. Push to main — CI sync will run automatically

Do NOT push to Confluence in scaffold mode.

---

Mode B — CI Sync (run on every push to main)

Triggered in CI. No interactive prompts. Fails fast on any error.

Step B1 — Verify environment

Check required env vars are set:

: "${CONFLUENCE_URL:?missing}"
: "${CONFLUENCE_USER:?missing}"
: "${CONFLUENCE_API_TOKEN:?missing}"

Exit 1 if any are missing.

Step B2 — Verify scaffold exists

test -d docs/engineering || exit 1

Exit 1 if docs/engineering/ does not exist (scaffold was not run).

Step B3 — Scan for eligible documents

Scan for files with mark headers:

find docs/engineering/adr docs/engineering/rfc docs/engineering/architecture \
  -name '*.md' -exec grep -l '<!-- Space:' {} \;

Step B4 — Diagram enforcement

Mermaid: Supported natively by mark. No action needed.