Marklassian

A lightweight JavaScript library that transforms Markdown to the Atlassian Document Format (ADF). Built for easy integration with Atlassian products and APIs.

Visit our interactive playground to experiment with Markdown to ADF conversion in real-time.

Features

• Convert Markdown to ADF with a single function call
• Support for the most common Markdown syntax
• TypeScript-ready with full type definitions
• Works in all modern JavaScript environments (Browsers, Node.js, Deno, Bun)
• Lightweight (12kb gzipped and minified), doesn't depend on AtlasKit dependencies

Installation

npm install marklassian

Usage

import { markdownToAdf } from 'marklassian';

const markdown = '# Hello World';
const adf = markdownToAdf(markdown);

Supported Markdown Features

• Headings (H1-H6)
• Paragraphs and line breaks
• Emphasis (bold, italic, strikethrough)
• Links and images
• Code blocks with language support
• Ordered and unordered lists with nesting
• Blockquotes
• Horizontal rules
• Tables
• Task lists (GitHub Flavoured Markdown feature)

Embedding ADF nodes

For cases where Markdown doesn't cover a required Confluence or Jira structure (macros, panels, status badges, etc.), you can embed raw ADF nodes directly inside <adf> tags:

# My page

<adf>
{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"status","parameters":{"macroParams":{"title":{"value":"Done"},"colour":{"value":"Green"}}}}}
</adf>

More content here.

The content inside <adf>…</adf> must be either:

• A single JSON object with at least a "type" string property, or
• A JSON array of such objects

This matches the structure of a node in an ADF document's content array. All attrs, content, and marks fields are passed through unchanged.

If the tag content is not valid JSON, or any parsed value is not an object with a "type" string, markdownToAdf will throw an error.

⚠️ Please note

• <adf> must appear as a block-level element — surrounded by blank lines. Inline placement (e.g. inside a sentence) will result in the tag being treated as inline HTML and the content will not be parsed as ADF.
• The embedded ADF nodes are not processed or validated by this library. They are passed through verbatim into the output document. This means that you are responsible for ensuring that the embedded ADF is valid and correctly structured for your use case.

API Reference

markdownToAdf(markdown: string): AdfDocument

Converts a Markdown string to an ADF document object (JSON serialisable).

Types

type AdfNode = {
    type: string;
    attrs?: Record<string, any>;
    content?: AdfNode[];
    marks?: AdfMark[];
    text?: string;
};

type AdfMark = {
    type: string;
    attrs?: Record<string, any>;
};

type AdfDocument = {
    version: 1;
    type: 'doc';
    content: AdfNode[];
};

Caveats

Marklassian aims to provide a lightweight, fast and mostly accurate conversion from Markdown to ADF.

If you have complex Markdown or require strict conformance to the ADF format, you may need want to use the official Atlassian libraries. These are hefty dependencies that may bloat your project and require manual tree shaking.

The following example demonstrates how to use the official Atlassian libraries for Markdown to ADF conversion:

import { defaultSchema } from '@atlaskit/adf-schema';
import { JSONTransformer } from '@atlaskit/editor-json-transformer';
import { MarkdownTransformer } from '@atlaskit/editor-markdown-transformer';

const jsonTransformer = new JSONTransformer();
const markdownTransformer = new MarkdownTransformer(defaultSchema);

const markdownDocument = '';
const adfDocument = jsonTransformer.encode(markdownTransformer.parse(markdownDocument));

Sourced from https://jira.atlassian.com/browse/JRACLOUD-77436

References

For those interested in the ADF format, the following resources may be helpful:

• Atlassian Document Format (ADF) Reference
• Atlassian Document Format Interactive Builder
• @atlaskit/adf-utils, an official Atlassian library for working with ADF documents. Provides validation and a Java-like builder API for creating ADF documents.

License

MIT