adf-builder

Atlassian Document Format Builder (JavaScript)

A library that simplifies building documents that follow the Atlassian Document Format structure.

Installation

Install the package using

npm i -S adf-builder

or

yarn add adf-builder

Usage

This package offers two ways of building documents:

• A fluent document builder interface with support for all node types
• A tag to be used with ES6 template literals for single-paragraph documents

Fluent Interface

import { Document } from 'adf-builder'; // For TypeScript or ES6
// const { Document } = require('adf-builder'); // For node/commonjs

const doc = new Document();
doc.paragraph()
  .text('See the ')
  .link('documention', 'https://example.com')
  .text(' ')
  .emoji('smile');

Tagged Template Literals

import { document, emoji, link } from 'adf-builder'; // For TypeScript or ES6
// const { document, emoji, link } = require('adf-builder'); // For node/commonjs

const doc = document`See the ${link('documentation', 'https://example.com')} ${emoji('smile')}`;

Serialization

A document can be serialized in different ways:

const doc = new Document();
doc.toJSON();        // Returns the Atlassian Document Format structure
doc.toString();      // Returns a compact JSON string
JSON.stringify(doc); // Equivalent to 'doc.toString()', but can be used for pretty printing

Code completion

If you use the library with TypeScript or with an IDE that interprets the index.d.ts file declared in package.json for JavaScript projects, you will get automatic code completion.

Examples

Simple paragraphs

In order to get an output like:

Hello @joe, please carefully read this contract

You would use:

const { Document } = require('adf-builder');

const doc = new Document();
doc.paragraph()
  .text('Hello ')
  .mention(id, 'joe')
  .text(', please ')
  .em('carefully')
  .text(' read ')
  .link('this contract', 'https://www.example.com/contract');

Text

The Paragraph class has some convenience methods for text with a single mark like strong, link, etc.

If you need more than one mark, you can use the marks builder:

const { Document, marks } = require('adf-builder');

const doc = new Document();
doc.paragraph()
  .text('Formatted', marks().color('#f0f0f0').strong());

Application Card

doc.applicationCard('Title')
  .background('https://example.com/bg.png')
  .link('https://example.com/something')
  .description('Some description')
  .detail()
    .title('Status')
    .text('Open')
    .icon({url: 'https://example.com/open.png', title: 'Not resolved yet'});

Lists

For lists, there are some convenience methods that cover the simple cases. Consider a list like the following:

• Do this first
• Do this second

In order to create that list, you can use:

doc.bulletList()
  .textItem('Do this first')
  .textItem('Do this second');

Similarly for lists of links:

doc.orderedList()
  .linkItem('Do this first', 'https://example.com/1')
  .linkItem('Do this second', 'https://example.com/1');

For more complex use cases, use:

const list = doc.bulletList();
list.item().paragraph().text('a'); // add more to the paragraph
list.item().paragraph().text('b'); // add more to the paragraph

Contributing

TBD