Extended ADF Markdown Parser

> 📖 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

``bash
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.

$3

Works in Node.js projects, TypeScript projects compiling to CommonJS, and any environment expecting CommonJS modules:
`javascript
const { Parser } = require('extended-markdown-adf-parser');

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

$3


Works in modern Node.js projects, browsers, and TypeScript projects using ES modules:
`javascript
import { Parser } from 'extended-markdown-adf-parser';

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

$3


Works in both CommonJS and ESM environments:
`javascript
const { Parser } = await import('extended-markdown-adf-parser');

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

$3


Full type definitions for all module systems:
`typescript
import { Parser, type ADFDocument, type ConversionOptions } from 'extended-markdown-adf-parser';
// or
const { Parser } = require('extended-markdown-adf-parser');
`

$3

- 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

$3

`typescript
// 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
`

$3

`typescript
// 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"
---

Main Document Title

This is a justified paragraph with custom line spacing that demonstrates the full capabilities of the Extended ADF Markdown Parser.

~~~panel type=info title="Important Information"
This panel contains important information with custom styling.

- 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 |

~~~expand title="Additional Resources"
This expandable section contains additional resources and links for further reading.

External Documentation
~~~;

// 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);
`

$3

#### Metadata Comments
Apply custom attributes to any element:
`markdown

This paragraph is centered.




Custom Heading


`

#### ADF Fence Blocks
`markdown
~~~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
~~~

~~~mediaGroup
!Image 1
!Image 2
~~~
`

#### Nested ADF Fence Blocks ✨ _New in v2.2.0_
ADF fence blocks can now be nested within each other, enabling complex document structures:

`markdown
~~~expand title="Project Overview"

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

~~~mediaSingle layout=wide
!Architecture Diagram
~~~

~~~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
`markdown


Media placeholders

!Alt text

User mentions

{user:username}
{user:user-id-123}

Media references

{media:media-id-456}
`

#### Frontmatter Support
`yaml
---
title: "Document Title"
author: "Author Name"
tags: [tag1, tag2, tag3]
metadata:
custom: "value"
---
`

Architecture

$3

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:

`typescript
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):
`typescript
const parser = new Parser({ enableAdfExtensions: true });
const enhanced = new EnhancedMarkdownParser();
`

After (v2.1.6+):
`typescript
// 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.

$3

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

$3

`bash


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