Extended ADF Markdown Parser

2.4.0 verified Sat Apr 25 auth: no javascript

A bidirectional parser v2.4.0 for converting between Atlassian Document Format (ADF) and Extended Markdown. Released under MIT license with monthly updates, it supports all major ADF elements including panels, expands, media, tables, status, emoji, mentions, dates, and code blocks. Key differentiators: advanced nested processing via multi-pass parsing, metadata annotation for full fidelity, zero runtime dependencies, dual CJS/ESM module support, and 100% test coverage. Requires Node >=20.11.1 and ships TypeScript types.

Common errors

error TypeError: process.memoryUsage is not a function ↓

cause Using v2.2.x or earlier in browser environment (React, Vite, etc.) due to Node-specific API.

fix

Upgrade to v2.3.0+ which removes performance monitor dependencies.

error SyntaxError: Named export 'parseAdfToMarkdown' not found. The requested module 'extended-markdown-adf-parser' is a CommonJS module. ↓

cause Using named ESM imports with a CJS module in older versions without proper dual module support.

fix

Upgrade to v1.1.0+ which provides dual CJS/ESM support; ensure bundler is configured correctly.

error ValidationError: Unknown attribute 'style' in node type 'status' ↓

cause Using deprecated 'style' attribute in status syntax after v2.3.1.

fix

Use official 'color' attribute with valid color names: neutral, green, red, yellow, blue, purple.

error Error: Node.js version must be >=20.11.1 ↓

cause Attempting to install or run on a Node.js version below the required minimum.

fix

Install or switch to Node.js v20.11.1 or higher using nvm or similar.

Warnings

breaking v2.3.0 replaced performance monitor with browser-compatible implementation, removing process.memoryUsage(). Code relying on that functionality will break. ↓

fix Upgrade to v2.3.0+ or remove custom performance monitoring calls.

deprecated parseAdfToMarkdown and parseMarkdownToAdf are the preferred imports over Parser class since v2.0.0. Using Parser will still work but may be removed in future major version. ↓

fix Replace Parser usage with named function imports.

gotcha Extended Markdown syntax uses non-standard extensions like {info}, {expand}, and {status}. Standard Markdown parsers will not render these correctly. ↓

fix Use this library for both parsing and rendering, or convert to ADF first and use Atlassian renderer.

gotcha Emoji short names must include colons (e.g., :grinning:) in v2.2.0+; older v1.x required no colons. ↓

fix Use colon-enclosed short names like :grinning: instead of grinning.

deprecated Status element color attribute changed in v2.3.1: 'style' attribute removed in favor of 'color' with official Atlassian color names. ↓

fix Use color:green|red|yellow|blue|purple in status syntax instead of style attribute.

breaking v2.2.0 introduced multi-pass nested processing which changed the internal API of ExtendedMarkdownParser. Custom implementations depending on earlier pass logic may break. ↓

fix Update any custom parser extensions to use the new multi-pass API.

gotcha The package requires Node.js >=20.11.1. Older Node versions will fail to install or run. ↓

fix Upgrade Node.js to v20.11.1+.

Install

npm install extended-markdown-adf-parser

yarn add extended-markdown-adf-parser

pnpm add extended-markdown-adf-parser

Imports

parseAdfToMarkdown

wrong

const parseAdfToMarkdown = require('extended-markdown-adf-parser').parseAdfToMarkdown

correct

import { parseAdfToMarkdown } from 'extended-markdown-adf-parser'

Default function exported as named export, not default. ESM and CJS both supported since v1.1.0.

parseMarkdownToAdf

wrong

import parseMarkdownToAdf from 'extended-markdown-adf-parser'

correct

import { parseMarkdownToAdf } from 'extended-markdown-adf-parser'

Named export only. Default export is not provided.

Parser

wrong

const Parser = require('extended-markdown-adf-parser').Parser

correct

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

Class export, available as named export in both ESM and CJS. TypeScript type definitions included.

ExtendedMarkdownParser

wrong

import ExtendedMarkdownParser from 'extended-markdown-adf-parser'

correct

import { ExtendedMarkdownParser } from 'extended-markdown-adf-parser'

Named export for advanced parsing with multi-pass processing. Only in v2.2.0+.

Quickstart

Shows bidirectional conversion between Extended Markdown and Atlassian Document Format, including panels and expands.

import { parseAdfToMarkdown, parseMarkdownToAdf } from 'extended-markdown-adf-parser';

// Extended Markdown string
const markdown = `# Hello World

This is a paragraph with **bold** and *italic* text.

{info}A note panel{info}

{expand:Expandable Section}
Content inside the expand block.
{expand}
`;

// Convert to ADF
const adf = parseMarkdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));

// Convert back to Markdown
const markdownAgain = parseAdfToMarkdown(adf);
console.log(markdownAgain);