node_media

class atlas_doc_parser.nodes.node_media.NodeMediaAttrs(type: Literal['file', 'link', 'external'] = REQ, id: str = OPT, collection: str = OPT, url: str = OPT, localId: str = OPT, alt: str = OPT, width: int = OPT, height: int = OPT, occurrenceKey: str = OPT)[source]

Attributes for NodeMedia.

There are two variants based on the type attribute:

Internal media (type=”file” or “link”):

  • type, id, collection are required

External media (type=”external”):

  • type, url are required

Parameters:

  • type – Required. The media type: “file”, “link”, or “external”.

  • id – Required for internal media. The Media Services ID for API queries.

  • collection – Required for internal media. The Media Services Collection identifier.

  • url – Required for external media. The external URL of the media.

  • localId – Optional. A unique identifier for the node.

  • alt – Optional. Alternative text for the media (accessibility).

  • width – Optional. Display width in pixels.

  • height – Optional. Display height in pixels.

  • occurrenceKey – Optional. Enables file deletion from collections when present.

class atlas_doc_parser.nodes.node_media.NodeMedia(type: str = 'media', attrs: NodeMediaAttrs = REQ, marks: list[MarkLink | MarkAnnotation | MarkBorder] = OPT)[source]

A media node in ADF representing a file, link, or external media.

The media node represents a single file or link stored in media services. It is a child block node that can only be nested within mediaGroup or mediaSingle nodes.

There are two variants:

  • Internal media (type=”file” or “link”): References media stored in Atlassian’s Media Services, identified by id and collection.

  • External media (type=”external”): References external media via url.

Reference:

https://developer.atlassian.com/cloud/jira/platform/apis/document/nodes/media/

to_markdown(ignore_error: bool = False) → str[source]

Convert this node to Markdown format.

The default implementation raises NotImplementedError. This is intentional for several reasons:

  1. Fail fast during development. When implementing new node types, we want to immediately discover which nodes haven’t implemented to_markdown() rather than silently producing empty output or skipping content. This helps catch missing implementations early.

  2. The ignore_error parameter provides an escape hatch. In production, if our code has bugs or a node type is partially implemented, users can pass ignore_error=True to gracefully skip nodes that fail to convert. This flag should be propagated recursively to all nested to_markdown() calls via helper functions like content_to_markdown().

  3. Error handling is explicit. The library user decides whether to fail fast (for debugging and development) or degrade gracefully (for production use cases where partial output is acceptable).

Subclasses must override this method to provide actual conversion logic.

Parameters:

ignore_error – If True, errors in nested conversions are silently skipped. If False (default), errors propagate immediately. This flag should be passed down to any nested to_markdown() calls.

Returns:

The Markdown representation of this node.

Raises:

NotImplementedError – Always raised by the base class to ensure subclasses implement this method.