marklas 0.1.0__tar.gz

marklas-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: marklas
+Version: 0.1.0
+Summary: Bidirectional converter between GitHub Flavored Markdown and Atlassian Document Format
+Author: byExist
+Author-email: byExist <jongbeom.kwon@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Dist: mistune>=3.2
+Requires-Dist: black>=26.1.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
+Requires-Python: >=3.13
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# marklas
+
+Bidirectional conversion library between GFM (GitHub Flavored Markdown) and ADF (Atlassian Document Format).
+
+Converts between Markdown and ADF via an intermediate AST representation.
+
+```
+ADF ──parser──▶ AST ──renderer──▶ Markdown
+Markdown ──parser──▶ AST ──renderer──▶ ADF
+```
+
+## Installation
+
+```bash
+pip install marklas
+```
+
+## Usage
+
+### Markdown → ADF
+
+```python
+from marklas.parser.md import parse
+from marklas.renderer.adf import render
+
+doc = parse("**Hello** world")
+adf = render(doc)
+# {
+#   "type": "doc",
+#   "version": 1,
+#   "content": [
+#     {
+#       "type": "paragraph",
+#       "content": [
+#         {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
+#         {"type": "text", "text": " world"}
+#       ]
+#     }
+#   ]
+# }
+```
+
+### ADF → Markdown
+
+```python
+from typing import Any
+
+from marklas.parser.adf import parse
+from marklas.renderer.md import render
+
+adf: dict[str, Any] = {
+    "type": "doc",
+    "version": 1,
+    "content": [
+        {
+            "type": "paragraph",
+            "content": [
+                {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
+                {"type": "text", "text": " world"},
+            ],
+        }
+    ],
+}
+doc = parse(adf)
+md = render(doc)
+# "**Hello** world\n"
+```
+
+## Conversion Rules
+
+### Block
+
+| ADF                                        | AST                                              | Markdown                      |
+| ------------------------------------------ | ------------------------------------------------ | ----------------------------- |
+| `paragraph`                                | `Paragraph(children)`                            | inline content                |
+| `heading` (level 1-6)                      | `Heading(level, children)`                       | `# ~ ######`                  |
+| `codeBlock` (language?)                    | `CodeBlock(code, language?)`                     | ` ```lang\ncode\n``` `        |
+| `blockquote`                               | `BlockQuote(children)`                           | `> text`                      |
+| `bulletList > listItem`                    | `BulletList(items) > ListItem(children)`         | `- item`                      |
+| `orderedList > listItem`                   | `OrderedList(items, start) > ListItem(children)` | `1. item`                     |
+| `taskList > taskItem`                      | `BulletList > ListItem(checked=bool)`            | `- [x]` / `- [ ]`             |
+| `decisionList > decisionItem`              | `BulletList > ListItem(checked=bool)`            | `- [x]` / `- [ ]`             |
+| `rule`                                     | `ThematicBreak`                                  | `---`                         |
+| `table > tableRow > tableHeader/tableCell` | `Table(head, body, alignments)`                  | GFM table                     |
+| `mediaSingle > media` (external)           | `Paragraph > Image(url, alt)`                    | `![alt](url)`                 |
+| `mediaSingle > media` (non-external)       | `Paragraph > Text("[Image: id]")`                | `[Image: id]`                 |
+| `mediaGroup > media`                       | `Paragraph > Image/Text`                         | `![alt](url)` / `[Image: id]` |
+| `panel`                                    | `BlockQuote(children)`                           | `> text`                      |
+| `expand` / `nestedExpand` (title?)         | `BlockQuote(children)` (title prepended)         | `> title\n> text`             |
+| `layoutSection > layoutColumn`             | flattened blocks                                 | columns flattened             |
+| `blockCard` (url)                          | `Paragraph > Link(url)`                          | `[url](url)`                  |
+| `embedCard` (url)                          | `Paragraph > Link(url)`                          | `[url](url)`                  |
+
+### Inline
+
+| ADF                    | AST                           | Markdown            |
+| ---------------------- | ----------------------------- | ------------------- |
+| `text`                 | `Text(text)`                  | plain text          |
+| `text` + `strong` mark | `Strong(children)`            | `**text**`          |
+| `text` + `em` mark     | `Emphasis(children)`          | `*text*`            |
+| `text` + `strike` mark | `Strikethrough(children)`     | `~~text~~`          |
+| `text` + `code` mark   | `CodeSpan(code)`              | `` `code` ``        |
+| `text` + `link` mark   | `Link(url, children, title?)` | `[text](url)`       |
+| `hardBreak`            | `HardBreak`                   | `\` + newline       |
+| —                      | `SoftBreak`                   | newline             |
+| `mention`              | `CodeSpan(code)`              | `` `@user` ``       |
+| `emoji`                | `Text(text)`                  | `:shortName:`       |
+| `date`                 | `CodeSpan(code)`              | `` `2024-01-01` ``  |
+| `status`               | `CodeSpan(code)`              | `` `status text` `` |
+| `inlineCard` (url)     | `Link(url)`                   | `[url](url)`        |
+| —                      | `Image(url, alt, title?)`     | `![alt](url)`       |
+
+### Not Supported
+
+| Element                                                                | Behavior             |
+| ---------------------------------------------------------------------- | -------------------- |
+| ADF marks: `underline`, `textColor`, `backgroundColor`, `subsup`       | silently ignored     |
+| ADF blocks: `extension`, `bodiedExtension`, `syncBlock`, `bodiedSyncBlock` | `[type]` placeholder |
+| ADF inlines: `placeholder`, `inlineExtension`, `mediaInline`           | `[type]` placeholder |
+| ADF table: `colspan`, `rowspan`                                        | expanded with empty cells |
+| ADF table: `background`, `colwidth`                                    | attributes ignored   |
+| ADF table: non-paragraph cell content                                  | `[type]` placeholder |
+| Markdown: raw HTML (block, inline)                                     | silently ignored     |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest -v
+uv run black src/ tests/
+```

marklas-0.1.0/README.md

@@ -0,0 +1,131 @@
+# marklas
+
+Bidirectional conversion library between GFM (GitHub Flavored Markdown) and ADF (Atlassian Document Format).
+
+Converts between Markdown and ADF via an intermediate AST representation.
+
+```
+ADF ──parser──▶ AST ──renderer──▶ Markdown
+Markdown ──parser──▶ AST ──renderer──▶ ADF
+```
+
+## Installation
+
+```bash
+pip install marklas
+```
+
+## Usage
+
+### Markdown → ADF
+
+```python
+from marklas.parser.md import parse
+from marklas.renderer.adf import render
+
+doc = parse("**Hello** world")
+adf = render(doc)
+# {
+#   "type": "doc",
+#   "version": 1,
+#   "content": [
+#     {
+#       "type": "paragraph",
+#       "content": [
+#         {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
+#         {"type": "text", "text": " world"}
+#       ]
+#     }
+#   ]
+# }
+```
+
+### ADF → Markdown
+
+```python
+from typing import Any
+
+from marklas.parser.adf import parse
+from marklas.renderer.md import render
+
+adf: dict[str, Any] = {
+    "type": "doc",
+    "version": 1,
+    "content": [
+        {
+            "type": "paragraph",
+            "content": [
+                {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
+                {"type": "text", "text": " world"},
+            ],
+        }
+    ],
+}
+doc = parse(adf)
+md = render(doc)
+# "**Hello** world\n"
+```
+
+## Conversion Rules
+
+### Block
+
+| ADF                                        | AST                                              | Markdown                      |
+| ------------------------------------------ | ------------------------------------------------ | ----------------------------- |
+| `paragraph`                                | `Paragraph(children)`                            | inline content                |
+| `heading` (level 1-6)                      | `Heading(level, children)`                       | `# ~ ######`                  |
+| `codeBlock` (language?)                    | `CodeBlock(code, language?)`                     | ` ```lang\ncode\n``` `        |
+| `blockquote`                               | `BlockQuote(children)`                           | `> text`                      |
+| `bulletList > listItem`                    | `BulletList(items) > ListItem(children)`         | `- item`                      |
+| `orderedList > listItem`                   | `OrderedList(items, start) > ListItem(children)` | `1. item`                     |
+| `taskList > taskItem`                      | `BulletList > ListItem(checked=bool)`            | `- [x]` / `- [ ]`             |
+| `decisionList > decisionItem`              | `BulletList > ListItem(checked=bool)`            | `- [x]` / `- [ ]`             |
+| `rule`                                     | `ThematicBreak`                                  | `---`                         |
+| `table > tableRow > tableHeader/tableCell` | `Table(head, body, alignments)`                  | GFM table                     |
+| `mediaSingle > media` (external)           | `Paragraph > Image(url, alt)`                    | `![alt](url)`                 |
+| `mediaSingle > media` (non-external)       | `Paragraph > Text("[Image: id]")`                | `[Image: id]`                 |
+| `mediaGroup > media`                       | `Paragraph > Image/Text`                         | `![alt](url)` / `[Image: id]` |
+| `panel`                                    | `BlockQuote(children)`                           | `> text`                      |
+| `expand` / `nestedExpand` (title?)         | `BlockQuote(children)` (title prepended)         | `> title\n> text`             |
+| `layoutSection > layoutColumn`             | flattened blocks                                 | columns flattened             |
+| `blockCard` (url)                          | `Paragraph > Link(url)`                          | `[url](url)`                  |
+| `embedCard` (url)                          | `Paragraph > Link(url)`                          | `[url](url)`                  |
+
+### Inline
+
+| ADF                    | AST                           | Markdown            |
+| ---------------------- | ----------------------------- | ------------------- |
+| `text`                 | `Text(text)`                  | plain text          |
+| `text` + `strong` mark | `Strong(children)`            | `**text**`          |
+| `text` + `em` mark     | `Emphasis(children)`          | `*text*`            |
+| `text` + `strike` mark | `Strikethrough(children)`     | `~~text~~`          |
+| `text` + `code` mark   | `CodeSpan(code)`              | `` `code` ``        |
+| `text` + `link` mark   | `Link(url, children, title?)` | `[text](url)`       |
+| `hardBreak`            | `HardBreak`                   | `\` + newline       |
+| —                      | `SoftBreak`                   | newline             |
+| `mention`              | `CodeSpan(code)`              | `` `@user` ``       |
+| `emoji`                | `Text(text)`                  | `:shortName:`       |
+| `date`                 | `CodeSpan(code)`              | `` `2024-01-01` ``  |
+| `status`               | `CodeSpan(code)`              | `` `status text` `` |
+| `inlineCard` (url)     | `Link(url)`                   | `[url](url)`        |
+| —                      | `Image(url, alt, title?)`     | `![alt](url)`       |
+
+### Not Supported
+
+| Element                                                                | Behavior             |
+| ---------------------------------------------------------------------- | -------------------- |
+| ADF marks: `underline`, `textColor`, `backgroundColor`, `subsup`       | silently ignored     |
+| ADF blocks: `extension`, `bodiedExtension`, `syncBlock`, `bodiedSyncBlock` | `[type]` placeholder |
+| ADF inlines: `placeholder`, `inlineExtension`, `mediaInline`           | `[type]` placeholder |
+| ADF table: `colspan`, `rowspan`                                        | expanded with empty cells |
+| ADF table: `background`, `colwidth`                                    | attributes ignored   |
+| ADF table: non-paragraph cell content                                  | `[type]` placeholder |
+| Markdown: raw HTML (block, inline)                                     | silently ignored     |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest -v
+uv run black src/ tests/
+```

marklas-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "marklas"
+version = "0.1.0"
+description = "Bidirectional converter between GitHub Flavored Markdown and Atlassian Document Format"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "byExist", email = "jongbeom.kwon@gmail.com" }
+]
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+]
+dependencies = ["mistune>=3.2"]
+
+[project.optional-dependencies]
+dev = [
+    "black>=26.1.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"

marklas-0.1.0/src/marklas/__init__.py

@@ -0,0 +1,3 @@
+from marklas.ast.blocks import Document
+
+__all__ = ["Document"]

marklas-0.1.0/src/marklas/ast/base.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Node:
+    pass

marklas-0.1.0/src/marklas/ast/blocks.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from marklas.ast.base import Node
+from marklas.ast.inlines import Inline
+
+
+@dataclass
+class Block(Node):
+    pass
+
+
+@dataclass
+class Document(Node):
+    children: list[Block]
+
+
+@dataclass
+class Paragraph(Block):
+    children: list[Inline]
+
+
+@dataclass
+class Heading(Block):
+    level: Literal[1, 2, 3, 4, 5, 6]
+    children: list[Inline]
+
+
+@dataclass
+class CodeBlock(Block):
+    code: str
+    language: str | None = None
+
+
+@dataclass
+class BlockQuote(Block):
+    children: list[Block]
+
+
+@dataclass
+class ThematicBreak(Block):
+    pass
+
+
+@dataclass
+class ListItem(Block):
+    children: list[Block]
+    checked: bool | None = None
+
+
+@dataclass
+class BulletList(Block):
+    items: list[ListItem]
+    tight: bool = True
+
+
+@dataclass
+class OrderedList(Block):
+    items: list[ListItem]
+    start: int = 1
+    tight: bool = True
+
+
+@dataclass
+class TableCell(Node):
+    children: list[Inline]
+
+
+@dataclass
+class Table(Block):
+    head: list[TableCell]
+    body: list[list[TableCell]]
+    alignments: list[Literal["left", "center", "right"] | None] = field(
+        default_factory=list[Literal["left", "center", "right"] | None]
+    )

marklas-0.1.0/src/marklas/ast/inlines.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from marklas.ast.base import Node
+
+
+@dataclass
+class Inline(Node):
+    pass
+
+
+@dataclass
+class Text(Inline):
+    text: str
+
+
+@dataclass
+class Strong(Inline):
+    children: list[Inline]
+
+
+@dataclass
+class Emphasis(Inline):
+    children: list[Inline]
+
+
+@dataclass
+class Strikethrough(Inline):
+    children: list[Inline]
+
+
+@dataclass
+class Link(Inline):
+    url: str
+    children: list[Inline]
+    title: str | None = None
+
+
+@dataclass
+class Image(Inline):
+    url: str
+    alt: str = ""
+    title: str | None = None
+
+
+@dataclass
+class CodeSpan(Inline):
+    code: str
+
+
+@dataclass
+class HardBreak(Inline):
+    pass
+
+
+@dataclass
+class SoftBreak(Inline):
+    pass