Atlassian Document Builder

0.5.2 · active · verified Thu Apr 16

The `atlassian-doc-builder` library, currently at version 0.5.2, provides a programmatic way to create Atlassian Documents (ADF) for platforms like Confluence and Jira. It enables developers to automate report publication and generate structured content, supporting a tree-like document representation, JSON ADF rendering, parsing, and document validation. The project maintains an active release cadence with regular updates.

Common errors

```
ADF validation failed: 'content' is a required property (or similar JSON schema validation error)
```
cause The generated Atlassian Document Format (ADF) JSON does not conform to the official Atlassian schema. This often happens due to missing required attributes or incorrect nesting of nodes.

fix Carefully review the `atlassian-doc-builder` documentation and examples for the specific ADF node you are trying to create. Ensure all required attributes are provided and that child nodes are placed correctly according to the ADF specification. Use `doc.dumps(indent=2)` to visualize the output JSON.
```
AttributeError: 'ADFText' object has no attribute 'add_node'
```
cause You are attempting to add a child node to an ADF object (like `ADFText`) that cannot contain other nodes. Only certain block-level and parent nodes (e.g., `ADFDocument`, `ADFParagraph`, `ADFBulletList`, `ADFTable`) can have child nodes.

fix Understand the hierarchical structure of ADF. `ADFText` is a leaf node and should be placed within a parent that accepts text (e.g., `ADFParagraph`, `ADFListItem`). Adjust your code to add text directly to appropriate parent nodes or construct the correct nested structure.
```
TypeError: 'list' object is not callable when trying to chain .add_node()
```
cause This error occurs if you try to chain `.add_node()` calls after assigning the result of a `doc.add_node()` call to a variable, and `add_node` implicitly returned the document's content list instead of `self` for chaining.

fix Ensure `add_node` or similar methods return `self` to enable chaining. If the library's method returns the content, you'll need to call `.add_node()` directly on the intended parent object in separate statements.

Warnings

breaking Version 0.5.2 updated the internal `adf_schema` URL. While this is a fix, custom validation logic or direct interaction with schema URLs based on older versions might encounter issues if they relied on the previous URL.
Fix: Ensure your environment fetches the latest schema or update any hardcoded schema references if you're performing external schema validation.
gotcha The library heavily relies on building a tree-like structure that strictly adheres to the Atlassian Document Format (ADF) schema. Incorrect nesting or invalid child nodes will result in malformed ADF that may fail validation or render incorrectly on Atlassian platforms.
Fix: Always refer to the official Atlassian Document Format documentation and the library's examples to understand valid node hierarchies and attributes. Use `doc.dumps(indent=2)` to inspect the generated JSON and debug structure issues.
gotcha Version 0.4 introduced `ADFTable` objects and index-based access (e.g., `doc[1,2,3]`) for child nodes. While not directly breaking, this introduces new patterns for document manipulation.
Fix: Familiarize yourself with the new table creation routines and index access methods when working with tabular data or complex document structures. Existing code for non-table elements should remain compatible.

Install

pip install atlassian-doc-builder Install stable version

Imports

ADFDocument
```
from atlassian_doc_builder import ADFDocument
```
The core class for building an Atlassian Document.
ADFParagraph
```
from atlassian_doc_builder import ADFParagraph
```
Commonly used for text content within a document.
ADFText
```
from atlassian_doc_builder import ADFText
```
Used for plain text within ADF nodes.
ADFLink
```
from atlassian_doc_builder import ADFLink
```
For embedding hyperlinks in the document.
ADFStatus
```
from atlassian_doc_builder import ADFStatus
```
For creating status lozenges in the document, as introduced in v0.5.1.

Quickstart

This quickstart demonstrates how to create a basic Atlassian Document (ADF) with paragraphs, text, and a link, then outputs its JSON representation.

from atlassian_doc_builder import ADFDocument, ADFParagraph, ADFText, ADFLink

# Create a new Atlassian Document
doc = ADFDocument()

# Add a paragraph with plain text
doc.add_node(ADFParagraph().add_node(ADFText("Hello, Atlassian Document Builder!")))

# Add another paragraph with text and a link
paragraph_with_link = ADFParagraph()
paragraph_with_link.add_node(ADFText("Visit the "))
paragraph_with_link.add_node(ADFLink(text="official GitHub repository", href="https://github.com/khwong-c/atlassian-doc-builder"))
paragraph_with_link.add_node(ADFText(" for more examples."))
doc.add_node(paragraph_with_link)

# Print the generated ADF JSON (for demonstration, in a real app you might save or upload this)
print(doc.dumps(indent=2))

view raw JSON →