Metadata-Version: 2.4
Name: marklassian
Version: 0.1.0
Summary: Convert Markdown to Atlassian Document Format (ADF)
Project-URL: Homepage, https://github.com/mbroton/marklassian-py
Project-URL: Repository, https://github.com/mbroton/marklassian-py
Author-email: Michał Brotoń <michal@broton.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: adf,atlassian,confluence,jira,markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: mistune>=3.0.0
Description-Content-Type: text/markdown

# marklassian-py

A lightweight Python library that converts Markdown to the [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). Built for easy integration with Atlassian products like Jira and Confluence.

This is a Python port of the excellent [marklassian](https://github.com/jamsinclair/marklassian) JavaScript library by [@jamsinclair](https://github.com/jamsinclair).

## Features

- Convert Markdown to ADF with a single function call
- Support for common Markdown syntax including GFM task lists
- Minimal dependencies (only [mistune](https://github.com/lepture/mistune))
- Full type hints for IDE support
- Python 3.10+

## Installation

```bash
pip install marklassian
```

Or with uv:

```bash
uv add marklassian
```

## Usage

```python
from marklassian import markdown_to_adf

markdown = "# Hello World\n\nThis is **bold** and *italic* text."
adf = markdown_to_adf(markdown)
```

The result is a dictionary that can be serialized to JSON:

```python
import json
print(json.dumps(adf, indent=2))
```

## Supported Markdown Features

- Headings (H1-H6)
- Paragraphs and line breaks
- Emphasis (bold, italic, strikethrough)
- Links and images
- Inline code and code blocks with language support
- Ordered and unordered lists with nesting
- Blockquotes
- Horizontal rules
- Tables
- Task lists (GitHub Flavored Markdown)

## API Reference

### `markdown_to_adf(markdown: str) -> AdfDocument`

Converts a Markdown string to an ADF document object.

### Types

```python
class AdfMark(TypedDict, total=False):
    type: Required[str]
    attrs: dict[str, Any]

class AdfNode(TypedDict, total=False):
    type: Required[str]
    attrs: dict[str, Any]
    content: list[AdfNode]
    marks: list[AdfMark]
    text: str

class AdfDocument(TypedDict):
    version: Literal[1]
    type: Literal["doc"]
    content: list[AdfNode]
```

## Caveats

This library aims to provide a lightweight and mostly accurate conversion from Markdown to ADF.

For complex Markdown documents or strict ADF conformance requirements, consider using the official Atlassian libraries. Note that those are heavier dependencies.

## References

- [Atlassian Document Format Reference](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
- [ADF Interactive Builder](https://developer.atlassian.com/cloud/jira/platform/apis/document/playground/)
- [Original marklassian (JavaScript)](https://github.com/jamsinclair/marklassian)

## Credits

This library is a Python port of [marklassian](https://github.com/jamsinclair/marklassian) by [Jamie Sinclair](https://github.com/jamsinclair). All credit for the original implementation and conversion logic goes to them.

## License

MIT - see [LICENSE](LICENSE) for details.
