Developer
News and Updates
Get Support
Sign in
Get Support
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Last updated Nov 11, 2026

Convert ADF to plain text

Technical Guide

Introduction

Rich content often has to go somewhere that cannot display it, such as an email subject line, a notification, a log message, or a full-text search index. For these, ADF can be rendered as plain text, which here means text with no styling. Bold, italics, colors, and the other marks are dropped, and by default so are link targets and mention IDs.

Some of the document's structure still survives as simple textual markers. List items start with * or 1. , quotes start with > , table rows are written as |cell|cell|, and media, extensions, and other nodes with no textual form are replaced by short placeholders such as [media]. These markers come from the Atlaskit editor's text renderer and are meant for a human reader. Nothing is escaped, so text that happens to start with * or contain | looks just like a list or a table, and the output cannot be parsed back into ADF. Callers who need structure that can be read back should use Markdown instead.

Converting ADF to plain text is therefore lossy, and what is worth keeping depends on what the text is for. A search index benefits from link targets and mention IDs, while a notification preview usually does not. The configuration controls these choices.

Historically, this library provided plain text through Node.toPlainText(), which each node implements for itself. Its behavior could only be adjusted through the Feature Context, which made it awkward to offer more than a couple of options. PlainTextTransformer replaces it with a single transformer whose output is controlled by an ordinary configuration object. Node.toPlainText() is now deprecated and will be removed in a future major release.

PlainTextTransformer

Experimental

PlainTextTransformer is part of the core adf-builder-java module, in the com.atlassian.adf.plaintext package, so no additional dependency is required. Along with PlainTextConfig and PlainText, it should be considered EXPERIMENTAL. Its default output is verified against Node.toPlainText(), but its API is subject to change.

Example

Java

1
2
3
4
5
6
7
8
9
10
doc(
    p(text("See "), text("the docs").link("https://example.com/docs"), text(" and ask "), mention("abc123")),
    blockCard("https://example.atlassian.net/browse/ABC-123"),
    ul(
        li(p("First")),
        li(p("Second"))
    ),
    mediaSingle(fileMedia("file-id", "coll").alt("diagram.png"))
)

Usage

1
2
3
4
    PlainTextTransformer transformer = new PlainTextTransformer();
    String text = transformer.toPlainText(doc);
    // text == "See the docs and ask @unknown\n* First\n* Second\n[media]"

With no configuration, the output is identical to that of Node.toPlainText() with no features enabled.

Supported nodes

With the default configuration, the nodes that this library supports are rendered as shown in this table.

ADF nodePlain-text output
paragraph, heading, caption, codeBlockinline content run together and trimmed, with a space added after a mention that is followed directly by text
doc, expand, nestedExpand, layoutSection, layoutColumn, bodiedRule, bodiedSyncBlock, taskList, decisionListone block per line, with blank lines collapsed and any expand title dropped
panelone block per line, with blank lines kept, though a doc or other container in the row above that holds the panel collapses them along with the rest of its content
blockquote> followed by its blocks run together
bulletList, orderedList* item or 1. item, numbered from the list's order, with nested lists not indented
taskItem, blockTaskItem, decisionItem[] item or [x] item for a task, and <> item for a decision
tableone row per line, as |cell|cell|
hardBreaka line break
rulenothing
textthe text alone, with all marks including links dropped
mentionits text, or @unknown when it has none, with @all and @here kept as they are
emojithe emoji character, or its short name (e.g. :grin:)
dateYYYY-MM-DD
status[ TEXT ] in capitals
placeholderits text
inlineCardits URL
blockCard, embedCardnothing
mediaSingle[media], followed by the caption
mediaGroupa count of its files (e.g. ๐Ÿ“Ž 2 Files)
mediaInline[mediaInline]
extension, inlineExtension, bodiedExtension, multiBodiedExtensionits text attribute, otherwise its node type in brackets (e.g. [extension])
syncBlock[syncBlock]

Nodes that this library does not recognize render their text or attrs.text property if they have one, and otherwise their node type in brackets.

Configuration

A PlainTextConfig controls how the nodes whose plain-text form is lossy are rendered. It is immutable, so it can be defined once and shared between transformers, and its builder starts from the defaults, so only the settings that should differ need to be given.

1
2
3
4
5
6
7
8
9
10
11
    PlainTextConfig config = PlainTextConfig.builder()
            .mentions(MentionStyle.NAME_AND_ID)
            .links(LinkStyle.TEXT_AND_URL)
            .media(MediaStyle.ALT_TEXT_AND_ID)
            .cards(CardStyle.URL)
            .build();
    PlainTextTransformer transformer = new PlainTextTransformer(config);
    String text = transformer.toPlainText(doc);
    // text == "See the docs (https://example.com/docs) and ask @[abc123]\n"
    //       + "https://example.atlassian.net/browse/ABC-123\n* First\n* Second\n[diagram.png (file-id)]"

Each setting has the styles shown in this table. The last column shows which styles the defaults() and detailedText() settings use.

SettingStyleRendersUsed by
mentions (mention)UNKNOWN_WHEN_NAMELESS@Fred, or @unknown when it has no namedefaults(), detailedText()
ID_WHEN_NAMELESS@Fred, or @[abc123] when it has no name
NAME_AND_ID@Fred (abc123), or @[abc123] when it has no name
ID_ONLY@[abc123]
links (link marks)TEXT_ONLYdocsdefaults(), detailedText()
TEXT_AND_URLdocs (url), and [media] (url) for linked media
media (media, mediaSingle, mediaInline, and the items of a mediaGroup)PLACEHOLDER[media] or [mediaInline]defaults()
ALT_TEXT_AND_ID[alt (id)], or [id] when it has no alt textdetailedText()
ALT_TEXT[alt], or [media] when it has no alt text
mediaGroups (mediaGroup)FOLLOW_MEDIACOUNT under PLACEHOLDER media, and ITEMS under the other media stylesdefaults()
COUNT๐Ÿ“Ž 2 Files
ITEMS[media], [media]
COUNT_AND_ITEMS๐Ÿ“Ž 2 Files: [media], [media]detailedText()
extensions (extension, inlineExtension, bodiedExtension, multiBodiedExtension)NODE_TYPEits text, or [inlineExtension]defaults()
KEY_AND_CONTENTits text, or [inlineExtension:jira], then its body on a new linedetailedText()
TEXT_ONLYits text, then its body on a new line
PLACEHOLDER_ONLY[inlineExtension:jira]
OMITnothing
cards (blockCard, embedCard)OMITnothingdefaults()
URLits URL, or nothing for a blockCard with none
URL_OR_PLACEHOLDERits URL, or [blockCard] for a blockCard with nonedetailedText()
PLACEHOLDER[blockCard] or [embedCard]
inlineCards (inlineCard)URLits URLdefaults()
TYPED_ISSUE_KEY_OR_URLABC-123 for a card made from an issue key typed as text, otherwise its URLdetailedText()
blockquotes (blockquote)CONCATENATED> followed by its blocks run togetherdefaults()
SEPARATEDeach block on its own line, with > at the start of every linedetailedText()
blankLines (the whole document)COLLAPSEDno blank linesdefaults()
CONTENT_ONLYonly the blank lines in the contentdetailedText()
AS_RENDEREDevery blank line, including empty paragraphs
expands (expand, nestedExpand)CONTENT_ONLYits contentdefaults()
TITLE_AND_CONTENTits title, then its content on a new linedetailedText()
lists (bulletList, orderedList)FLATnested lists not indenteddefaults()
INDENTEDnested lists indented under their item, as in * a\n * bdetailedText()
unsupported (nodes the library could not parse)NODE_TYPEits text, or its node type in bracketsdefaults(), detailedText()
TEXT_ONLYits text, or nothing
syncBlocks (syncBlock)PLACEHOLDER[syncBlock]defaults(), detailedText()
RESOURCE_ID[some-resource-id]
rules (rule)OMITnothingdefaults()
DASHES----detailedText()
emptyBlocks (codeBlock, panel, expand, nestedExpand)OMIT_IF_BLANKnothing when the block has no textdefaults()
PLACEHOLDER_IF_BLANK[codeBlock], [panel], [expand] or [nestedExpand] when the block has no textdetailedText()

A few more points about these settings.

  • TEXT_AND_URL shows a link's URL once, after the whole link, and not at all when the text already is the URL.
  • A mediaGroup count stands for the whole group, so it shows none of its files' URLs. Listed items show their own.
  • An inlineCard follows the inlineCards setting, whatever the cards setting.
  • When Jira makes an inlineCard from an issue key typed as text, such as See ABC-123 in wiki markup, it marks the card's URL with #icft=KEY, as in https://example.atlassian.net/browse/ABC-123#icft=ABC-123. TYPED_ISSUE_KEY_OR_URL renders such a card as its key, ABC-123, as it was typed. A pasted link to an issue has no marker, so it still renders as its URL.

Detailed text

PlainTextConfig.detailedText() gives settings for the document's text with its details, the things that say what each part of the document is or holds. The document's own text is written in reading order, including the body of an extension and the title of an expand, and an issue key typed as text that became an inline card is written as the key that was typed. Content that the document only refers to is identified rather than shown. Media renders as its alt text and ID, since ADF holds no file names, a media group as a count of its files followed by each of them, an inline card that was not typed as an issue key as its URL, a block or embed card as its URL, or [blockCard] when it has none, and a sync block as [syncBlock]. An extension with no text renders as its node type and key, such as [inlineExtension:jira], and a bodied extension follows this with its body on a new line, since an app can show, hide, or transform the body. A node the library cannot render shows its text, or otherwise its node type, such as [someNewNode].

The structure a reader sees is kept. Nested lists are indented, each line of a blockquote starts with > , and list markers, check boxes, table cell separators, and status brackets remain. A rule renders as ----, and a code block, panel or expand with no text as its node type, such as [codeBlock], since a reader still sees it. Only the blank lines in the content are kept.

1
2
3
    PlainTextTransformer transformer = new PlainTextTransformer(PlainTextConfig.detailedText());
    String text = transformer.toPlainText(doc);

The text is close to what a reader sees, but not the same, as it holds the details that identify what the page shows. Where the page shows an image, a preview, or a macro's output, the text has the alt text and ID, the URL, or a placeholder that stands for it. Start from it with PlainTextConfig.detailedText().copy() to change any of its settings.

Unlike Node.toPlainText(), the transformer ignores the Feature Context, so its output depends on its configuration alone.

Questions about the text

Many uses of plain text only need part of it: whether a description is blank, whether it mentions something, or perhaps the first couple of hundred characters for a preview. plainText(node) returns a PlainText that answers these without rendering the whole document.

1
2
3
4
5
6
7
    PlainText text = new PlainTextTransformer().plainText(issue.getDescription());
    if (text.isBlank()) {
        return Optional.empty();
    }
    boolean mentionsOutage = text.contains("outage");
    String preview = text.truncate(200);

With the document from the example above, whose full text is "See the docs and ask @unknown\n* First\n* Second\n[media]":

1
2
3
4
5
6
    PlainText text = new PlainTextTransformer().plainText(doc);
    text.isBlank();           // false, after rendering only the first paragraph
    text.contains("First");   // true, after rendering the list as well
    text.contains("Third");   // false, after rendering the rest
    text.truncate(12);        // "See the docs", from the text already rendered

A document whose blocks render only whitespace, or nothing at all, is blank, and truncate never cuts an emoji in half:

1
2
3
4
    PlainTextTransformer transformer = new PlainTextTransformer();
    transformer.plainText(doc(p("  "), rule(), p())).isBlank();   // true
    transformer.plainText(doc(p("Ship it ๐Ÿš€"))).truncate(9);      // "Ship it ", since ๐Ÿš€ takes two characters

isBlank(), isEmpty(), and contains(value) give the same answers as the String methods of the same names would on the full text.

truncate(maxLength) gives the start of the text, at most maxLength chars long. It never cuts a character in the middle. Emoji, flags, and letters with accents or other marks can take up more than one char and are kept whole, so the result can be a little shorter than maxLength, or empty if the first character is longer. A result shorter than maxLength is therefore not a sign that it is the whole text. Keeping characters whole is a best effort: some joined letters, such as เค•เฅเคท, can still be cut between their parts, and so can a character longer than any people write, such as a letter carrying dozens of accents, which only text made to be awkward has.

maxLength counts chars, not the characters a reader sees. Some chars take up no space on screen but still count:

  • an accent stored as a separate mark after its letter, so รฉ is one char when stored as a single character and two when stored as e followed by the combining acute accent U+0301, though both look the same
  • vowel and tone marks in scripts such as Hindi, Thai, and Arabic
  • invisible characters, such as the zero-width joiner that joins ๐Ÿ‘ฉ and ๐Ÿ’ป into ๐Ÿ‘ฉโ€๐Ÿ’ป

toString() gives the entire transformed text.

Because a PlainText keeps what it has rendered, the node must not be changed while the PlainText is in use. Instances are not safe for use by more than one thread at a time.

Migrating from Node.toPlainText()

Replacing node.toPlainText() with new PlainTextTransformer().toPlainText(node) gives the same output, as long as no features are enabled. Callers that do enable the plain-text features, including through Context.GlobalDefaultFeatureProvider, should set the matching configuration instead, since the transformer ignores them.

1
2
3
4
5
6
    PlainTextConfig config = PlainTextConfig.builder()
            .mentions(MentionStyle.ID_WHEN_NAMELESS)  // was Feature.PLAINTEXT_MENTION_USE_ID
            .cards(CardStyle.URL)                     // was Feature.ENABLE_BLOCK_EMBED_CARD_URLS_PLAINTEXT
            .build();
    String text = new PlainTextTransformer(config).toPlainText(doc);

The Feature.PLAINTEXT_MENTION_USE_ID and Feature.ENABLE_BLOCK_EMBED_CARD_URLS_PLAINTEXT enum constants are deprecated and will be removed along with Node.toPlainText() in a future major release.

Further Reading

Rate this page: