Markdown Confluence Publisher (VS Code Extension)

Publish and synchronize Markdown documentation directly to Atlassian Confluence Cloud from VS Code, with native Confluence Callout Macros and optional Google Open Knowledge Format (OKF v0.2) metadata management.

✨ Features

• 🚀 Zero-Config Publishing: Right-click any standard .md file to publish immediately to Confluence.
• 🛠️ Interactive Metadata Helper: Easily add or update metadata fields (type, author, lastUpdate, folderId, spaceKey, tags) using interactive menus.
• 🎨 Confluence Native Macros:
  • Converts GitHub-style callouts (> [!NOTE], > [!WARNING], > [!TIP], > [!IMPORTANT]) into native Confluence Info/Note/Tip/Warning Macros.
  • Converts code blocks and Mermaid diagrams into native Confluence Code Macros.
  • Prevents title duplication in Confluence page headers.
• 📁 Space & Folder Hierarchy: Organize pages into Confluence spaces and parent folders using spaceKey and folderId.
• ⚡ Right-Click Context Menu & Command Palette: Quick actions directly in Explorer and Editor views.

📥 Installation

Install directly from VS Code Marketplace, Open VSX Registry, or download the .vsix release package:

1. Open VS Code and go to the Extensions view (Cmd + Shift + X or Ctrl + Shift + X).
2. Search for Markdown Confluence Publisher.
3. Click Install.

⚙️ Setup & Configuration

🔑 1. Obtaining your Atlassian API Token

To publish documents to Confluence Cloud, you need an Atlassian API Token:

1. Log in to your Atlassian Account and navigate to id.atlassian.com/manage-profile/security/api-tokens.
2. Click Create API token.
3. Enter a label (e.g. VSCode-Confluence-Publisher) and click Create.
4. Copy the generated token string.

🧙‍♂️ 2. Interactive First-Run Setup (Zero-Config)

You don't need to manually configure settings before starting! The first time you publish a document or run a command:

• If any credential or setting is missing, the extension will prompt you interactively in VS Code for:
  • Atlassian Domain (e.g., your-company.atlassian.net)
  • Account Email (e.g., developer@company.com)
  • API Token
  • Default Space Key (e.g., DOCS, ENG, DEV)
• Your responses are automatically saved into your VS Code Workspace settings (.vscode/settings.json) or Global User Settings, so you only ever have to enter them once.

⚙️ 3. Workspace vs. Global Configuration

You can configure settings globally (for all projects) or per-workspace:

VS Code Settings (Cmd + , -> Search Markdown Confluence):

{
  "markdownConfluence.domain": "your-company.atlassian.net",
  "markdownConfluence.email": "your_email@domain.com",
  "markdownConfluence.apiToken": "your_api_token",
  "markdownConfluence.defaultSpaceKey": "DOCS",
  "markdownConfluence.defaultAuthorName": "Jorge Guzmán",
  "markdownConfluence.defaultFolderId": "376209618",
  "markdownConfluence.autoUpdateLastUpdate": true
}

Workspace Environment Files (.env.local / .env.confluence / .env):

Alternatively, store credentials in a .env file in your project root:

CONFLUENCE_DOMAIN=your-company.atlassian.net
CONFLUENCE_EMAIL=your_email@domain.com
CONFLUENCE_API_TOKEN=your_api_token
CONFLUENCE_DEFAULT_SPACE=DOCS
CONFLUENCE_DEFAULT_FOLDER_ID=376209618

🔧 Configuration Options Reference

📋 Metadata Fields Reference (OKF v0.2)

You can manage document metadata manually via YAML frontmatter or interactively using Cmd + Shift + P -> Markdown Confluence: Add/Edit Metadata Fields....

📄 Complete Example Document

---
type: architecture
title: "Dashboard Statistics & Automations Engine"
description: "Technical specification for monthly KPIs, automated task triggers, and market intelligence widgets."
tags: [dashboard, analytics, database, cron]
generated: { by: "human:developer", at: "2026-07-26T13:09:03.370Z" }
lastUpdate: "2026-07-27T10:45:00.000Z"
spaceKey: DOCS
folderId: "12345678"
fileId: "87654321"
---

# Dashboard Statistics & Automations Engine

> [!NOTE] This document is written in Markdown and synchronized with Atlassian Confluence Cloud.

## 1. System Overview

The system processes real-time analytics events through Cloud Functions and updates Firestore counters reactively.

```mermaid
graph TD
    A[Client Event] --> B[Cloud Function]
    B --> C[Firestore Document]
    C --> D[Angular Dashboard Widget]
```

[!TIP] Use Cmd + Shift + P -> Markdown Confluence: Add/Edit Metadata Fields... to quickly set Space Key or Parent Folder interactively.

📦 Commands Reference

• Markdown Confluence: Publish Current File — Publish or update the current file in Confluence Cloud. If frontmatter metadata is missing, automatically launches the interactive pre-publish metadata wizard.
• Markdown Confluence: Add/Edit Metadata Fields... — Interactive QuickPick menu to view, add, or update individual frontmatter metadata fields (title, type, spaceKey, folderId, generated, tags, description, fileId).

📜 Changelog

Version 1.1.1 (2026-08-05)

• ⚡ Lightweight Remote Space Search (CQL):
  • What: Replaced bulk page fetching in parent folder pickers with a lightweight Confluence Query Language (CQL) search engine (searchSpacePages). Loads 25 recent pages initially and allows searching any page across large Confluence spaces remotely by title.
  • Why: Drastically reduces network bandwidth and memory consumption on large Confluence spaces (5,000+ pages) while ensuring instant search results.

Version 1.1.0 (2026-08-05)

• 🚀 Interactive Pre-Publish Metadata Wizard:
  • What: When publishing a document without metadata, an interactive metadata wizard launches automatically, allowing users to review, edit, or customize metadata fields cumulatively before publishing.
  • Why: Prevents publishing documents with missing or unconfigured metadata, while guaranteeing sensible defaults (title from H1/filename, author from settings, type Wiki, default space, ISO timestamps) when fields are left untouched.
• 👤 Custom Default Author Resolution (defaultAuthorName):
  • What: Resolved markdownConfluence.defaultAuthorName configuration across all commands and formatted human author names automatically (e.g. Jorge Guzmán -> human:Jorge Guzmán).
  • Why: Ensures correct author attribution in generated: { by: ... } rather than falling back to telemetry-derived generic strings (human:user).
• 📁 Default Parent Folder/Page ID Configuration (defaultFolderId):
  • What: Added markdownConfluence.defaultFolderId setting and CONFLUENCE_DEFAULT_FOLDER_ID environment variable support.
  • Why: Allows users and teams to set a primary parent folder ID so newly created documents land in the intended section of Confluence without manual folder selection.
• 🧹 Streamlined Context Menu & Workflow:
  • What: Removed redundant commands (Sync Metadata, Update Timestamps & Author, Set Document Type, Set Parent Folder) from context menus, reducing right-click options to 2 clean actions: Publish Current File and Add/Edit Metadata Fields....
  • Why: Eliminates UI clutter and avoids destructive remote-body conversion attempts, maintaining the local Markdown document as the 100% pristine Source of Truth.

Version 1.0.2 (Initial Stable Release)

• 🌟 Initial release of Markdown Confluence Publisher with support for OKF v0.2 metadata format, GitHub-style callouts, Mermaid diagrams, and Atlassian Confluence Cloud API integration.

📜 License

MIT License — Created for Google Antigravity & Open Knowledge Framework ecosystems.