Introduction

📖 Official ADF Documentation: Atlassian Document Format Structure

A bidirectional parser for converting between Atlassian Document Format (ADF) and Extended Markdown.

Complete Documentation - Full guide with examples, API reference, and advanced usage patterns.

What is ADF? Atlassian Document Format (ADF) is a JSON-based document format used by Atlassian products like Jira and Confluence to represent rich content including text formatting, tables, panels, media, and other structured elements.

Features

• Bidirectional Conversion: Convert ADF to Extended Markdown and back Seamlessly transform content between Atlassian Document Format and Extended Markdown with complete round-trip fidelity.

• Extended Markdown Syntax: Support for ADF-specific elements like panels, expands, and media Beyond standard Markdown, includes ADF extensions such as info panels, expandable sections, and media placeholders with full nested structure support.

• Advanced Nested Processing ✨ New in v2.2.0: Multi-pass parsing for complex nested ADF structures Comprehensive nested ADF fence block processing enables complex document hierarchies with panels containing media, expandable sections with sub-panels, and unlimited nesting depth.

• Full Fidelity: Preserves all ADF attributes through metadata annotations Custom attributes and styling information are maintained using HTML comment metadata, ensuring no data loss during conversion.

• Universal Module Support: True dual package with zero configuration Supports CommonJS require(), ESM import, and dynamic import() with automatic format selection, bundled dependencies, and complete TypeScript compatibility.

• Type Safe: Written in TypeScript with complete type definitions Full TypeScript support with comprehensive type definitions for all ADF nodes, ensuring compile-time safety and excellent IDE support.

• Comprehensive Test Coverage: 100% test coverage with 399 tests across 29 test suites Thoroughly tested with integration tests, unit tests, and fixture validation covering all ADF node types and conversion scenarios.

• Zero Runtime Dependencies: Lightweight and portable (uses well-established libraries) Built on proven libraries like unified/remark ecosystem, with no additional runtime dependencies for your applications.

Supported Elements

This parser provides bidirectional conversion support between Markdown and ADF. The table below shows all supported elements and their conversion capabilities:

Element Type	ADF Node	Description	Markdown → ADF	ADF → Markdown
DOCUMENT STRUCTURE
Document	doc	Root document container	✓	✓
Paragraph	paragraph	Text paragraphs with attributes	✓	✓
Hard Break	hardBreak	Explicit line breaks	✓	✓
Text	text	Raw text content	✓	✓
HEADINGS
Heading L1	heading	Level 1 heading	✓	✓
Heading L2	heading	Level 2 heading	✓	✓
Heading L3	heading	Level 3 heading	✓	✓
Heading L4	heading	Level 4 heading	✓	✓
Heading L5	heading	Level 5 heading	✓	✓
Heading L6	heading	Level 6 heading	✓	✓
TEXT FORMATTING
Bold	mark:strong	Bold text formatting	✓	✓
Italic	mark:em	Italic text formatting	✓	✓
Inline Code	mark:code	Inline code spans	✓	✓
Strikethrough	mark:strike	Crossed out text	✓	✓
Underline	mark:underline	Underlined text	✓	✓
Text Color	mark:textColor	Custom text colors	✓	✓
Background Color	mark:backgroundColor	Text background colors	✓	✓
Link	mark:link	Hyperlinks with titles	✓	✓
Subscript/Superscript	mark:subsup	Sub/superscript text	✓	✓
LISTS
Bullet List	bulletList	Unordered lists	✓	✓
Ordered List	orderedList	Numbered lists	✓	✓
List Item	listItem	Individual list items	✓	✓
TABLES
Table	table	Complete table structures	✓	✓
Table Row	tableRow	Individual table rows	✓	✓
Table Header	tableHeader	Table header cells	✓	✓
Table Cell	tableCell	Regular table cells	✓	✓
QUOTES & CODE
Blockquote	blockquote	Quote blocks with nesting	✓	✓
Code Block	codeBlock	Fenced code blocks	✓	✓
Horizontal Rule	rule	Document dividers	✓	✓
ADF PANELS
Info Panel	panel	Information panels	✓	✓
Warning Panel	panel	Warning panels	✓	✓
Error Panel	panel	Error panels	✓	✓
Success Panel	panel	Success panels	✓	✓
Note Panel	panel	Note panels	✓	✓
MEDIA ELEMENTS
Media	media	Individual media items	✓	✓
Media Single	mediaSingle	Single media with layout	✓	✓
Media Group	mediaGroup	Multiple media grouped	✓	✓
INTERACTIVE ELEMENTS
Expand	expand	Collapsible content sections	✓	✓
Inline Card	inlineCard	Embedded link previews	✓	✓
SOCIAL ELEMENTS
Mention	mention	User mentions	✓	✓
Emoji	emoji	Emoji characters	✓	✓
Date	date	Date stamps	✓	✓
Status	status	Status indicators	✓	✓

Installation

npm install extended-markdown-adf-parser
# or
yarn add extended-markdown-adf-parser

Module Support

This package provides full dual package support for both CommonJS and ES Modules (ESM) with automatic format detection and zero configuration required.

✅ CommonJS Support

Works in Node.js projects, TypeScript projects compiling to CommonJS, and any environment expecting CommonJS modules:

const { Parser } = require('extended-markdown-adf-parser');

const parser = new Parser();
const adf = parser.markdownToAdf('# Hello World');

✅ ES Modules (ESM) Support

Works in modern Node.js projects, browsers, and TypeScript projects using ES modules:

import { Parser } from 'extended-markdown-adf-parser';

const parser = new Parser();
const adf = parser.markdownToAdf('# Hello World');

✅ Dynamic Import (Universal)

Works in both CommonJS and ESM environments:

const { Parser } = await import('extended-markdown-adf-parser');

const parser = new Parser();
const adf = parser.markdownToAdf('# Hello World');

✅ TypeScript Support

Full type definitions for all module systems:

import { Parser, type ADFDocument, type ConversionOptions } from 'extended-markdown-adf-parser';
// or
const { Parser } = require('extended-markdown-adf-parser');

Module Resolution Details

• Package Type: Dual package with proper exports configuration

• CommonJS Output: Bundled .cjs files with all dependencies included

• ESM Output: Tree-shakable .mjs files with external dependencies

• Automatic Selection: Node.js automatically selects the correct format

• Zero Configuration: No build tools or configuration changes required

Usage

Simple Example

// Choose your preferred import method - both work identically
import { Parser } from 'extended-markdown-adf-parser';           // ESM
// const { Parser } = require('extended-markdown-adf-parser');  // CommonJS

const parser = new Parser();

// Convert ADF to Extended Markdown
const adf = {
  type: 'doc',
  version: 1,
  content: [
    {
      type: 'paragraph',
      content: [
        { type: 'text', text: 'Hello World' }
      ]
    }
  ]
};

const markdown = parser.adfToMarkdown(adf);
console.log(markdown); // "Hello World"

// Convert Extended Markdown back to ADF
const reconstructed = parser.markdownToAdf(markdown);
console.log(reconstructed); // Original ADF structure

Complex Example with ADF Extensions

// Works with both CommonJS and ESM
import { Parser } from 'extended-markdown-adf-parser';
// const { Parser } = require('extended-markdown-adf-parser');

// ADF extensions are enabled by default in the unified architecture
const parser = new Parser();

// Extended Markdown with metadata and ADF elements
const extendedMarkdown = `---
title: "Complete Document Example"
author: "Extended ADF Parser"
---

<!-- adf:heading id="main-title" textAlign="center" -->
# Main Document Title

<!-- adf:paragraph textAlign="justify" lineHeight="1.6" -->
This is a justified paragraph with custom line spacing that demonstrates the full capabilities of the Extended ADF Markdown Parser.

<!-- adf:panel backgroundColor="#e6f7ff" borderColor="#1890ff" -->
~~~panel type=info title="Important Information"
This panel contains important information with custom styling.

<!-- adf:bulletList bulletStyle="square" -->
- Custom styled bullet list
- With square bullets
- Inside the panel
~~~

## Standard Markdown Section

This section uses standard Markdown without ADF extensions:

- **Bold text**
- *Italic text*  
- \`Inline code\`
- ~~Strikethrough~~

\`\`\`javascript
// Code block with syntax highlighting
function example() {
    return "Hello, World!";
}
\`\`\`

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

<!-- adf:expand defaultOpen="true" -->
~~~expand title="Additional Resources"
This expandable section contains additional resources and links for further reading.

[External Documentation](https://example.com)
~~~`;

// Convert to ADF
const adf = parser.markdownToAdf(extendedMarkdown);

// Convert back to markdown
const reconstructedMarkdown = parser.adfToMarkdown(adf);

console.log('ADF Document:', JSON.stringify(adf, null, 2));
console.log('Reconstructed Markdown:', reconstructedMarkdown);

Extended Markdown Syntax

Metadata Comments

Apply custom attributes to any element:

<!-- adf:paragraph textAlign="center" -->
This paragraph is centered.

<!-- adf:heading id="custom-id" anchor="custom-anchor" -->
# Custom Heading

ADF Fence Blocks

~~~panel type=info title="Information"
Content with **formatting** inside panels.
~~~

~~~expand title="Click to expand" expanded=true
Collapsible content that starts expanded.
~~~

~~~mediaSingle layout=center width=80
![Description](media:media-id-here)
~~~

~~~mediaGroup
![Image 1](media:id-1)
![Image 2](media:id-2)
~~~

Nested ADF Fence Blocks ✨ New in v2.2.0

ADF fence blocks can now be nested within each other, enabling complex document structures:

~~~expand title="Project Overview"

~~~panel type=warning title="Important Notice"
Please review the requirements before proceeding.
~~~

~~~mediaSingle layout=wide
![Architecture Diagram](media:diagram-123)
~~~

~~~panel type=success title="Status"
All tests passing ✅
~~~

~~~

Supported nested patterns:

• ~~~expand containing panels, media, and other expandable sections

• ~~~panel with nested media blocks and sub-panels

• Complex multi-level nesting with full content parsing

• All ADF fence types: panel, expand, nestedExpand, mediaSingle, mediaGroup

Media References

# Media placeholders
![Alt text](media:media-id-123)

# User mentions  
{user:username}
{user:user-id-123}

# Media references
{media:media-id-456}

Frontmatter Support

---
title: "Document Title"
author: "Author Name"
tags: [tag1, tag2, tag3]
metadata:
  custom: "value"
---

Architecture

Unified Parser Architecture (v2.1.6+)

The library has been completely refactored with a unified architecture that eliminates duplication and ensures consistent, high-quality conversions across all parser interfaces:

Core Components

1. Unified Parser Class - The main Parser class now uses shared conversion engines internally

2. MarkdownToAdfEngine - Dedicated engine for markdown → ADF conversion

3. AdfToMarkdownEngine - Dedicated engine for ADF → markdown conversion

4. Backward Compatibility - EnhancedMarkdownParser now simply extends Parser

Key Improvements

• 🎯 Consistent Results: All parsing approaches now produce identical, high-quality results

• ✨ No Configuration Required: ADF extensions are enabled by default (no more enableAdfExtensions flag)

• 🔧 Social Elements: Proper parsing of {user:mention}, :emoji:, {status:text}, and {date:YYYY-MM-DD} in all contexts

• ⚡ Performance: Shared engines eliminate code duplication and improve maintainability

• 🛡️ Error Recovery: Built-in error recovery with configurable retry strategies

Usage Patterns

All these approaches now produce identical results:

import { Parser, EnhancedMarkdownParser, MarkdownToAdfEngine } from 'extended-markdown-adf-parser';

// 1. Main Parser class (recommended)
const parser = new Parser();
const adf = parser.markdownToAdf(markdown);

// 2. Enhanced parser (backward compatibility)
const enhanced = new EnhancedMarkdownParser();
const adf2 = enhanced.parseSync(markdown);

// 3. Direct engine usage (for custom implementations)
const engine = new MarkdownToAdfEngine();
const adf3 = engine.convert(markdown);

// All produce identical results: adf === adf2 === adf3

Migration Guide

Before (v2.1.5 and earlier):

const parser = new Parser({ enableAdfExtensions: true });
const enhanced = new EnhancedMarkdownParser();

After (v2.1.6+):

// Simply use Parser - ADF extensions enabled by default
const parser = new Parser();

// EnhancedMarkdownParser still works (backward compatibility)
const enhanced = new EnhancedMarkdownParser();

Testing

This library includes a comprehensive test suite with 399 tests across 29 test suites, ensuring reliability and correctness across all supported features.

Test Categories

Integration Tests - End-to-end conversion and validation

• Markdown to ADF conversion with all supported elements

• Bidirectional round-trip conversion fidelity

• Enhanced parser with metadata comments support

• Media placeholders and ADF URL resolution

• Whitespace resilience and error handling

• Performance validation (avg <2ms per conversion)

Unit Tests - Individual component testing

• Parser classes (unified Parser, MarkdownToAdfEngine, AdfToMarkdownEngine)

• Node converters (panels, tables, media, lists, etc.)

• Mark converters (formatting, links, colors, etc.)

• Core components (converter registry, validators)

• Remark plugins and micromark extensions

Fixture Validation - Comprehensive markup coverage

• 17 markdown fixture files covering all ADF elements

• 11 corresponding ADF fixtures for validation

• 30+ ADF node types with complete attribute support

• Complex nested structures and edge cases

• Malformed input handling and recovery

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm test -- --testNamePattern="Integration"
npm test -- --testNamePattern="Unit"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT