VcMd2Conf — Markdown ↔ Confluence

Synchronize your Markdown documentation with Confluence using mark CLI — with visual sync status, one-click publish, and version tracking.

✨ Features

🌳 Sidebar Tree View

A dedicated Confluence Sync panel in the Activity Bar showing all your Markdown files with real-time sync status:

• ✅ Green — Synced and up to date
• ⚠️ Yellow — Modified locally, needs re-sync
• 🔴 Red — Has mark metadata but never synced
• ⚪ Grey — No mark metadata (Space/Title headers)
• ⬇️ Blue — Remote version is newer
• 🔄 Spinning — Currently syncing

📊 Two View Modes

Toggle between:

• 📁 By Folder — Files organized by directory structure
• 📊 By Status — Files grouped by sync status (actionable first)

🏷️ File Explorer Decorations

Visual badges directly on .md files in the VS Code Explorer:

• ✓ Synced | M Modified | N Not synced | ! Error | ↓ Remote newer

📈 Status Bar

Compact sync summary in the status bar:

• Shows count of files needing sync
• Warning background when action needed
• Click to focus the Confluence Sync panel

💡 Rich Tooltips

Hover over any file in the tree to see:

• Full mark metadata (Space, Title, Parents, Labels)
• Confluence page info (ID, version, last sync time)
• Remote version comparison
• Direct link to open in Confluence

⚡ Context Menu Integration

• Right-click any .md file → Sync to Confluence
• Right-click any folder → Sync Folder to Confluence
• Editor title bar → Sync button for active file

📋 Prerequisites

1. Install mark CLI

# macOS
brew install kovetskiy/mark/mark

# Go install
go install github.com/kovetskiy/mark/v17/cmd/mark@latest

# Or download binary from GitHub releases
# https://github.com/kovetskiy/mark/releases

2. Configure mark metadata in your Markdown files

Publishing enables --title-from-h1, so a leading H1 heading can supply the page title when no explicit title metadata is recognized. The extension enables frontmatter automatically for YAML metadata.

HTML Comment Headers (default):

<!-- Space: DOCS -->
<!-- Title: My Documentation Page -->
<!-- Parent: Guides -->

# My Documentation Page
Content here...

YAML Frontmatter

The extension enables mark's frontmatter feature automatically for file and folder publishing.

---
space: DOCS
title: My Documentation Page
parents:
  - Guides
labels:
  - documentation
---

# My Documentation Page
Content here...

⚙️ Configuration

Open VcMd2Conf: Configure Confluence Connection from the Command Palette, or use the gear button in the Confluence Sync view.

The configuration screen includes the Confluence URL, username/email, masked PAT/API token, default space, mark executable picker, features and optional mark configuration file. Save settings, test the connection, verify mark, or install it for the operating system running the extension (including remote hosts).

• Confluence Cloud: enter your email and API token; include /wiki in the URL.
• Confluence Server/Data Center PAT: leave the username empty to use Bearer authentication.
• Token storage: new tokens use VS Code SecretStorage, never the webview HTML. Leave the token field blank to keep it, or use the checkbox to delete it. Saving also moves the legacy vcmd2conf.apiToken setting into SecretStorage and removes its plaintext value from the active settings scopes.
• Settings scope: non-secret fields are saved to the current workspace, or user settings when no workspace is open. The token is stored per extension/user, not per workspace; changing it affects other workspaces using the extension.
• Install mark v17: installation requires confirmation and a trusted workspace. macOS/Linux use the official GitHub archive for the host CPU, verified against the release SHA-256 checksums. tar must be available. The current official release has no Windows archive: Windows falls back to go install, so install Go and restart VS Code first. The executable is kept in the extension's private storage and its path is saved automatically. No administrator privileges or system PATH changes are needed.
• Existing mark config: an explicit configuration file keeps priority for CLI authentication. The connection test uses the URL and token from this screen.

Failed sync notifications include the exit code, error details and a suggested fix, with Show Output and Configure actions. The output channel masks the configured token, and the token is passed to mark through stdin rather than CLI arguments. Mermaid rendering may additionally require Chrome/Chromium, depending on the mark renderer configuration.

Using a mark config file

If you have a ci.toml for mark:

base_url = "https://your-domain.atlassian.net/wiki"
user = "you@example.com"
password = "your-api-token"

Set vcmd2conf.markConfigPath to the path of your config file.

🎯 Commands

🔧 Development

# Install dependencies
npm install

# Build
npm run build

# Typecheck and focused tests
npm run typecheck
npm test

# Watch mode
npm run watch

# Package .vsix
npm run package

📄 License

MIT