https://github.com/jamsinclair/marklassian
Markdown to Atlassian Document Format (ADF) Converter
https://github.com/jamsinclair/marklassian
adf atlassian confluence javascript jira jira-rest-api markdown-converter markdown-to-adf markdown-transformer
Last synced: 2 months ago
JSON representation
Markdown to Atlassian Document Format (ADF) Converter
- Host: GitHub
- URL: https://github.com/jamsinclair/marklassian
- Owner: jamsinclair
- License: mit
- Created: 2025-01-26T11:08:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-24T05:18:42.000Z (3 months ago)
- Last Synced: 2026-03-25T06:30:42.119Z (3 months ago)
- Topics: adf, atlassian, confluence, javascript, jira, jira-rest-api, markdown-converter, markdown-to-adf, markdown-transformer
- Language: TypeScript
- Homepage: https://marklassian.netlify.app
- Size: 399 KB
- Stars: 23
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Marklassian
A lightweight JavaScript library that transforms Markdown to the [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). Built for easy integration with Atlassian products and APIs.
Visit our [interactive playground](https://marklassian.netlify.app/playground) to experiment with Markdown to ADF conversion in real-time.
[](https://www.npmjs.com/package/marklassian)
[](https://github.com/jamsinclair/marklassian/blob/main/LICENSE.md)
[](https://bundlephobia.com/package/marklassian)
## 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](https://bundlephobia.com/package/marklassian)), doesn't depend on AtlasKit dependencies
## Installation
```bash
npm install marklassian
```
## Usage
```javascript
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 `` tags:
```markdown
# My page
{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"status","parameters":{"macroParams":{"title":{"value":"Done"},"colour":{"value":"Green"}}}}}
More content here.
```
The content inside `…` 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
- `` 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
```typescript
type AdfNode = {
type: string;
attrs?: Record;
content?: AdfNode[];
marks?: AdfMark[];
text?: string;
};
type AdfMark = {
type: string;
attrs?: Record;
};
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:
```javascript
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
## References
For those interested in the ADF format, the following resources may be helpful:
- [Atlassian Document Format (ADF) Reference](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
- [Atlassian Document Format Interactive Builder](https://developer.atlassian.com/cloud/jira/platform/apis/document/playground/)
- [@atlaskit/adf-utils](https://www.npmjs.com/package/@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