{"id":8841,"library":"atlassian-doc-builder","title":"Atlassian Document Builder","description":"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.","status":"active","version":"0.5.2","language":"en","source_language":"en","source_url":"https://github.com/khwong-c/atlassian-doc-builder","tags":["atlassian","confluence","jira","adf","document-generation","document-builder","automation"],"install":[{"cmd":"pip install atlassian-doc-builder","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The core class for building an Atlassian Document.","symbol":"ADFDocument","correct":"from atlassian_doc_builder import ADFDocument"},{"note":"Commonly used for text content within a document.","symbol":"ADFParagraph","correct":"from atlassian_doc_builder import ADFParagraph"},{"note":"Used for plain text within ADF nodes.","symbol":"ADFText","correct":"from atlassian_doc_builder import ADFText"},{"note":"For embedding hyperlinks in the document.","symbol":"ADFLink","correct":"from atlassian_doc_builder import ADFLink"},{"note":"For creating status lozenges in the document, as introduced in v0.5.1.","symbol":"ADFStatus","correct":"from atlassian_doc_builder import ADFStatus"}],"quickstart":{"code":"from atlassian_doc_builder import ADFDocument, ADFParagraph, ADFText, ADFLink\n\n# Create a new Atlassian Document\ndoc = ADFDocument()\n\n# Add a paragraph with plain text\ndoc.add_node(ADFParagraph().add_node(ADFText(\"Hello, Atlassian Document Builder!\")))\n\n# Add another paragraph with text and a link\nparagraph_with_link = ADFParagraph()\nparagraph_with_link.add_node(ADFText(\"Visit the \"))\nparagraph_with_link.add_node(ADFLink(text=\"official GitHub repository\", href=\"https://github.com/khwong-c/atlassian-doc-builder\"))\nparagraph_with_link.add_node(ADFText(\" for more examples.\"))\ndoc.add_node(paragraph_with_link)\n\n# Print the generated ADF JSON (for demonstration, in a real app you might save or upload this)\nprint(doc.dumps(indent=2))","lang":"python","description":"This quickstart demonstrates how to create a basic Atlassian Document (ADF) with paragraphs, text, and a link, then outputs its JSON representation."},"warnings":[{"fix":"Ensure your environment fetches the latest schema or update any hardcoded schema references if you're performing external schema validation.","message":"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.","severity":"breaking","affected_versions":">=0.5.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ADF validation failed: 'content' is a required property (or similar JSON schema validation error)"},{"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.","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.","error":"AttributeError: 'ADFText' object has no attribute 'add_node'"},{"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.","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.","error":"TypeError: 'list' object is not callable when trying to chain .add_node()"}]}