markdown-to-adf_skill

Overview

This skill converts Markdown content into Confluence's ADF (Atlassian Document Format), producing ready-to-publish JSON for creating or updating Confluence pages. It preserves headings, lists, code blocks, tables, links, images, task lists, callouts, expands, mentions, and other common Markdown patterns.

How this skill works

The converter parses Markdown into an abstract syntax tree and maps nodes to ADF node types (paragraph, heading, bulletList, codeBlock, table, media, panel, etc.). It preserves text marks (bold, italic, code, strike, underline), link attributes, code block languages, table structure, and special Confluence extensions like panels, expand blocks, status badges, mentions, and emojis.

When to use it

• Publish README.md or technical docs to Confluence pages
• Automate documentation sync from a Markdown source to Confluence
• Update existing Confluence content using Markdown edits
• Convert code examples and fenced code blocks with language metadata
• Transform complex Markdown (tables, task lists, callouts) into ADF

Best practices

• Use fenced code blocks with language tags to keep syntax highlighting metadata
• Keep tables well-formed (consistent column counts) to avoid mapping errors
• Use Markdown task list syntax (- [ ] / - [x]) for Confluence taskList conversion
• Mark important notes with blockquote or explicit callout markers for panel conversion
• Validate the produced ADF JSON against Confluence API expectations before publishing

Example use cases

• Convert a project README into a Confluence page with preserved headings, links, and code samples
• Sync a docs folder to Confluence using a CI job that runs the converter and updates pages
• Generate ADF for pages that require Confluence-specific panels, expand sections, or status badges
• Transform Markdown-based release notes into Confluence-friendly tables and task lists
• Convert markdown blog drafts (images and links) into Confluence media and link nodes