Adf utils

Typescript ❤️

Set of utilities to traverse, modify and create ADF documents.

Install

yarn add @atlaskit/adf-utils

npm

Source

Bundle

Latest

19.19.0

Minor Changes

#120472 73c800ab5f2fc - ED-26766 update adf-schema from 47.2.1 to 47.6.0 and adf-schema-json from 1.27.0 to 1.31.0

Why?

Working with ADF might be tricky at times, especially extracting data or manipulating existing documents. This package provides a set of utilities to traverse, modify and create ADF documents.

Traverse

@atlaskit/adf-utils/traverse provides methods to extract and manipulate data inside an ADF document.

Example:

  import { traverse } from '@atlaskit/adf-utils/traverse.es'; // .es for ES2015

  const doc = {/* some ADF doc */};

  traverse(doc, {
    // emoji visitor, matches all nodes with type === 'emoji'
    emoji: (node, parent) => {
      // do something with the node
    },

    mention: (node, parent) => {
      // do something with mention
    },

    taskList: (node, parent) => {
      // do something with taskList
    }
  })

Example:

  import { map } from '@atlaskit/adf-utils/traverse.es'; // .es for ES2015

  const doc = {/* some ADF doc */};

  const allNodeTypesFromTheDoc = map(doc, node => node.type);

Example:

  import { filter } from '@atlaskit/adf-utils/traverse.es'; // .es for ES2015

  const doc = {/* some ADF doc */};

  const links = filter(
    doc,
    node =>
      (node.marks || []).some(mark => mark.type === 'link')
  );

Example:

  import { reduce } from '@atlaskit/adf-utils/traverse.es'; // .es for ES2015

  const doc = {/* some ADF doc */};

  const emojiString = reduce(
    doc,
    (acc, node) =>
      node.type === 'emoji'
        ? (acc += '| ' + node.attrs.text + ' – '  + node.attrs.shortName)
        : acc,
    '',
  );
  // Example output: | 😀 – :grinning:| 🤦‍♂️ – :man_facepalming:| 🇷🇺 – :flag_ru:

Builders

Builders are the set of composable functions that help with creating ADF documents.

@atlaskit/adf-utils provides builders for all nodes and marks listed in Atlassian Document Format specification.

Usage:

  import { doc, p, emoji } from '@atlaskit/adf-utils/builders.es'; // .es for ES2015

  const adfDoc = doc(
    p('My favourite emoji is ', emoji({ text: '🤦‍♂️', shortName: ':man_facepalming:' }), '. What is yours?'),
  );

  /**
   * Produces following output:
   *
   * {
   *   "type": "doc",
   *   "version": 1,
   *   "content": [
   *     {
   *       "type": "paragraph",
   *       "content": [
   *         {
   *           "type": "text",
   *           "text": "My favourite emoji is "
   *         },
   *         {
   *           "type": "emoji",
   *           "attrs": {
   *             "text": "🤦‍♂️",
   *             "shortName": ":man_facepalming:"
   *           }
   *         },
   *         {
   *           "type": "text",
   *           "text": ". What is yours?"
   *         }
   *       ]
   *     }
   *   ]
   * }
   */

Aliases

There are aliases for some of the nodes and marks that match html tag names:

Nodes:

paragraph -> p
bulletList -> ul
orderedList -> ol
listItem -> li
tableCell -> td
tableHeader -> th
tableRow -> tr
hardBreak -> br
rule -> hr

Marks:

link -> a
strong -> b
underline -> u