python-substack 0.7.0__tar.gz → 0.9.0__tar.gz

{python_substack-0.7.0 → python_substack-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.7.0
+Version: 0.9.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License: MIT
 License-File: LICENSE
@@ -94,6 +94,7 @@ Substack result:
 - Set audience, comment permissions, SEO metadata, slug, sections, and tags.
 - List and inspect publications and drafts.
 - Export drafts to loss-aware Markdown backups without server writes.
+- Safely update drafts from Markdown, preserving unsupported editor widgets by default.
 - Schedule, unschedule, publish, and delete drafts with explicit safeguards.
 - Use stable JSON envelopes in scripts and automation.
 - Authenticate with browser cookies or email and password.
@@ -145,6 +146,7 @@ substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
 substack drafts export 12345 --output backup.md
+substack drafts update 12345 revised-post.md --dry-run --yes
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -217,6 +219,17 @@ print(backup["markdown"])
 print(backup["unsupported_nodes"])
 ```
 
+Review a Markdown update before writing it, then update deliberately:
+
+```python
+result = api.update_draft_from_markdown(12345, "# Revised draft", dry_run=True)
+result = api.update_draft_from_markdown(12345, "# Revised draft")
+```
+
+Unsupported editor widgets exported as `python-substack-node:v1` markers are
+preserved by default. An update refuses to remove or alter them unless
+`allow_unsupported_change=True` is explicitly passed.
+
 For direct ProseMirror node construction, see the
 [low-level Python API](docs/low-level-api.md). YAML workflows are documented in
 [YAML drafts](docs/yaml.md).
@@ -269,11 +282,12 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Python SDK](docs/python-sdk.md)
 - [Authentication](docs/authentication.md)
 - [Markdown reference](docs/markdown.md)
+- [Draft backup and safe updates](docs/cli.md)
 - [Legacy CLI commands](docs/legacy-cli.md)
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
-- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Agent workflow](docs/agents.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

{python_substack-0.7.0 → python_substack-0.9.0}/README.md

@@ -58,6 +58,7 @@ Substack result:
 - Set audience, comment permissions, SEO metadata, slug, sections, and tags.
 - List and inspect publications and drafts.
 - Export drafts to loss-aware Markdown backups without server writes.
+- Safely update drafts from Markdown, preserving unsupported editor widgets by default.
 - Schedule, unschedule, publish, and delete drafts with explicit safeguards.
 - Use stable JSON envelopes in scripts and automation.
 - Authenticate with browser cookies or email and password.
@@ -109,6 +110,7 @@ substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
 substack drafts export 12345 --output backup.md
+substack drafts update 12345 revised-post.md --dry-run --yes
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -181,6 +183,17 @@ print(backup["markdown"])
 print(backup["unsupported_nodes"])
 ```
 
+Review a Markdown update before writing it, then update deliberately:
+
+```python
+result = api.update_draft_from_markdown(12345, "# Revised draft", dry_run=True)
+result = api.update_draft_from_markdown(12345, "# Revised draft")
+```
+
+Unsupported editor widgets exported as `python-substack-node:v1` markers are
+preserved by default. An update refuses to remove or alter them unless
+`allow_unsupported_change=True` is explicitly passed.
+
 For direct ProseMirror node construction, see the
 [low-level Python API](docs/low-level-api.md). YAML workflows are documented in
 [YAML drafts](docs/yaml.md).
@@ -233,11 +246,12 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Python SDK](docs/python-sdk.md)
 - [Authentication](docs/authentication.md)
 - [Markdown reference](docs/markdown.md)
+- [Draft backup and safe updates](docs/cli.md)
 - [Legacy CLI commands](docs/legacy-cli.md)
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
-- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Agent workflow](docs/agents.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

{python_substack-0.7.0 → python_substack-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.7.0"
+version = "0.9.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"

{python_substack-0.7.0 → python_substack-0.9.0}/substack/__init__.py

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.7.0"
+__version__ = "0.9.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

{python_substack-0.7.0 → python_substack-0.9.0}/substack/api.py

@@ -21,6 +21,19 @@ logger = logging.getLogger(__name__)
 __all__ = ["Api"]
 
 
+def _image_attrs(document):
+    images = []
+    if isinstance(document, dict):
+        if document.get("type") == "image2" and isinstance(document.get("attrs"), dict):
+            images.append(document["attrs"])
+        for value in document.values():
+            images.extend(_image_attrs(value))
+    elif isinstance(document, list):
+        for value in document:
+            images.extend(_image_attrs(value))
+    return images
+
+
 class Api:
     """
 
@@ -432,7 +445,10 @@ class Api:
             f"{self.publication_url}/drafts",
             params={"filter": filter, "offset": offset, "limit": limit},
         )
-        return Api._handle_response(response=response)
+        drafts = Api._handle_response(response=response)
+        if isinstance(drafts, dict) and isinstance(drafts.get("posts"), list):
+            return drafts["posts"]
+        return drafts
 
     def get_draft(self, draft_id):
         """
@@ -478,6 +494,8 @@ class Api:
         draft_section_id: int = None,
         tags=None,
         dry_run: bool = False,
+        allow_unsupported_change: bool = False,
+        allow_image_replacement: bool = False,
     ) -> dict:
         """
         Update an existing draft body from Markdown, with optional metadata changes.
@@ -497,12 +515,7 @@ class Api:
         if not isinstance(draft_body, dict):
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
-        _, unsupported_nodes = document_to_markdown(draft_body)
-        if unsupported_nodes:
-            raise ValueError(
-                "Refusing to update: remote draft contains unsupported Substack nodes. "
-                "Export it first or remove the nodes manually to avoid data loss."
-            )
+        _, remote_unsupported = document_to_markdown(draft_body)
 
         post = Post(
             title=draft.get("title", ""),
@@ -515,6 +528,48 @@ class Api:
         )
         post.from_markdown(markdown, api=self)
 
+        remote_images = _image_attrs(draft_body)
+        submitted_images = _image_attrs(post.draft_body)
+        for submitted in submitted_images:
+            matches = [
+                image
+                for image in remote_images
+                if image.get("src") == submitted.get("src")
+            ]
+            if len(matches) == 1:
+                source, alt, href = (
+                    submitted.get("src"),
+                    submitted.get("alt"),
+                    submitted.get("href"),
+                )
+                submitted.update(matches[0])
+                submitted.update(
+                    {"src": source, "alt": alt, "href": href, "isProcessing": False}
+                )
+            elif not allow_image_replacement:
+                raise ValueError(
+                    "Refusing to update: image cannot be matched uniquely; set allow_image_replacement=True to proceed."
+                )
+
+        _, submitted_unsupported = document_to_markdown(post.draft_body)
+
+        if not allow_unsupported_change:
+            remote_serialized = [
+                json.dumps(n, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+                for n in remote_unsupported
+            ]
+            submitted_serialized = [
+                json.dumps(n, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+                for n in submitted_unsupported
+            ]
+            if sorted(remote_serialized) != sorted(submitted_serialized):
+                raise ValueError(
+                    "Refusing to update: remote unsupported nodes are missing, duplicated, stale, or altered. "
+                    "Export the draft first or set allow_unsupported_change=True to proceed."
+                )
+
+        unsupported_nodes = remote_unsupported
+
         update_payload = {"draft_body": json.dumps(post.draft_body)}
 
         if subtitle is not None:

{python_substack-0.7.0 → python_substack-0.9.0}/substack/cli.py

@@ -310,6 +310,11 @@ def _drafts_create(api, args):
 
 
 def _drafts_update(api, args):
+    if args.allow_unsupported_change and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-unsupported-change")
+    if args.allow_image_replacement and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-image-replacement")
+
     if not args.yes and (args.json_output or not sys.stdin.isatty()):
         raise CLIUsageError("--yes is required in non-interactive or JSON mode")
 
@@ -347,6 +352,8 @@ def _drafts_update(api, args):
         draft_section_id=args.draft_section_id,
         tags=args.tags,
         dry_run=args.dry_run,
+        allow_unsupported_change=args.allow_unsupported_change,
+        allow_image_replacement=args.allow_image_replacement,
     )
 
     if args.json_output:
@@ -508,6 +515,8 @@ def _build_parser():
     drafts_update.add_argument("--draft-section-id", type=int)
     drafts_update.add_argument("--tag", action="append", dest="tags", metavar="TAG")
     drafts_update.add_argument("--dry-run", action="store_true")
+    drafts_update.add_argument("--allow-unsupported-change", action="store_true")
+    drafts_update.add_argument("--allow-image-replacement", action="store_true")
     drafts_update.add_argument("--yes", action="store_true")
     drafts_update.set_defaults(handler=_drafts_update)
 

{python_substack-0.7.0 → python_substack-0.9.0}/substack/mdexport.py

@@ -57,6 +57,21 @@ def _marker(node, unsupported):
     return f"<!-- python-substack-node:v1 {encoded} -->"
 
 
+def _image_marker(attrs):
+    preserved = {
+        key: value
+        for key, value in attrs.items()
+        if key not in {"src", "alt", "href", "isProcessing"}
+    }
+    if not preserved:
+        return ""
+    payload = json.dumps(
+        preserved, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    ).encode("utf-8")
+    encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    return f"\n<!-- python-substack-image:v1 {encoded} -->"
+
+
 def _require_dict(node, context):
     if not isinstance(node, dict):
         raise ValueError(f"Malformed draft body: {context} must be an object")
@@ -247,7 +262,7 @@ def _render_image(node, unsupported):
         if not isinstance(href, str):
             return _marker(node, unsupported)
         image_markdown = f"[{image_markdown}]({_escape_destination(href)})"
-    return image_markdown
+    return image_markdown + _image_marker(attrs)
 
 
 def _render_footnote(node, unsupported):

{python_substack-0.7.0 → python_substack-0.9.0}/substack/mdrender.py

@@ -1,248 +1,354 @@
-"""Markdown -> Substack ProseMirror via markdown-it-py.
-
-Implements Post.from_markdown() using a real CommonMark parser (markdown-it-py)
-plus the standard footnote plugin, with a small renderer that walks the syntax
-tree into Substack's node schema.
-
-Node construction goes through ``substack.nodes`` so the (undocumented) schema
-lives in exactly one place.
-
-Footnotes: Substack numbers footnote anchors by their position in the document
-and pairs them one-to-one, in order, with the footnote blocks at the end (it
-ignores any explicit number and does not support one block serving several
-anchors). So each reference is emitted as its own sequentially-numbered anchor,
-and a matching footnote block is appended for each -- a definition referenced
-more than once is duplicated, which mirrors how Substack's own editor behaves.
-"""
-
-from __future__ import annotations
-
-import copy
-from typing import Dict, List, Optional
-
-from markdown_it import MarkdownIt
-from markdown_it.tree import SyntaxTreeNode
-from mdit_py_plugins.container import container_plugin
-from mdit_py_plugins.dollarmath import dollarmath_plugin
-from mdit_py_plugins.footnote import footnote_plugin
-from mdit_py_plugins.subscript import sub_plugin
-from mdit_py_plugins.superscript import superscript_plugin
-
-from substack import nodes
-from substack.nodes import MarkType, NodeType
-
-_MARK_FOR = {
-    "strong": {"type": MarkType.STRONG},
-    "em": {"type": MarkType.EM},
-    "s": {"type": MarkType.STRIKETHROUGH},
-    "sup": {"type": MarkType.SUPERSCRIPT},
-    "sub": {"type": MarkType.SUBSCRIPT},
-}
-
-
-def _make_parser() -> MarkdownIt:
-    return (
-        MarkdownIt("commonmark")
-        .use(footnote_plugin)
-        # Pandoc-style delimiters: no whitespace just inside the dollars and no
-        # digit just outside them, so paired currency amounts ("$5 ... $10")
-        # stay plain text instead of becoming math.
-        .use(dollarmath_plugin, allow_space=False, allow_digits=False)
-        .use(sub_plugin)
-        .use(superscript_plugin)
-        .use(container_plugin, name="pullquote")
-        .use(container_plugin, name="callout")
-        .enable("strikethrough")
+"""Markdown -> Substack ProseMirror via markdown-it-py.
+
+Implements Post.from_markdown() using a real CommonMark parser (markdown-it-py)
+plus the standard footnote plugin, with a small renderer that walks the syntax
+tree into Substack's node schema.
+
+Node construction goes through ``substack.nodes`` so the (undocumented) schema
+lives in exactly one place.
+
+Footnotes: Substack numbers footnote anchors by their position in the document
+and pairs them one-to-one, in order, with the footnote blocks at the end (it
+ignores any explicit number and does not support one block serving several
+anchors). So each reference is emitted as its own sequentially-numbered anchor,
+and a matching footnote block is appended for each -- a definition referenced
+more than once is duplicated, which mirrors how Substack's own editor behaves.
+"""
+
+from __future__ import annotations
+
+import base64
+import copy
+import json
+import re
+from pathlib import Path
+from typing import Dict, List, Optional
+from urllib.parse import unquote, urlsplit
+
+from markdown_it import MarkdownIt
+from markdown_it.tree import SyntaxTreeNode
+from mdit_py_plugins.container import container_plugin
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.footnote import footnote_plugin
+from mdit_py_plugins.subscript import sub_plugin
+from mdit_py_plugins.superscript import superscript_plugin
+
+from substack import nodes
+from substack.nodes import MarkType, NodeType
+
+_MARK_FOR = {
+    "strong": {"type": MarkType.STRONG},
+    "em": {"type": MarkType.EM},
+    "s": {"type": MarkType.STRIKETHROUGH},
+    "sup": {"type": MarkType.SUPERSCRIPT},
+    "sub": {"type": MarkType.SUBSCRIPT},
+}
+
+
+def parse_node_marker(comment_content: str) -> dict | None:
+    """
+    Parse a python-substack-node:v1 comment marker and return the parsed JSON dictionary.
+
+    If it is not a python-substack-node:v1 marker, returns None.
+    If it is an attempted marker but is corrupt/malformed, raises ValueError.
+    """
+    clean = comment_content.strip()
+    match = re.match(
+        r"^<!--\s*python-substack-node:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
+    )
+    if not match:
+        if "python-substack-node:v1" in clean:
+            raise ValueError("Corrupt marker format")
+        return None
+
+    encoded = match.group(1)
+
+    try:
+        padding = len(encoded) % 4
+        if padding:
+            encoded += "=" * (4 - padding)
+        decoded_bytes = base64.urlsafe_b64decode(encoded.encode("ascii"))
+    except Exception as exc:
+        raise ValueError("Invalid URL-safe base64 in marker") from exc
+
+    try:
+        decoded_str = decoded_bytes.decode("utf-8")
+    except Exception as exc:
+        raise ValueError("Invalid UTF-8 in marker") from exc
+
+    try:
+        data = json.loads(decoded_str)
+    except Exception as exc:
+        raise ValueError("Invalid JSON in marker") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError("Marker payload is not a top-level JSON object")
+
+    node_type = data.get("type")
+    if not isinstance(node_type, str) or not node_type:
+        raise ValueError("Marker payload has missing or empty 'type'")
+
+    return data
+
+
+def parse_image_marker(comment_content: str) -> dict | None:
+    clean = comment_content.strip()
+    match = re.match(
+        r"^<!--\s*python-substack-image:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
     )
-
-
-def _coalesce(out_nodes: List[Dict]) -> List[Dict]:
-    """Merge adjacent text nodes that carry identical marks (e.g. softbreaks)."""
-    merged: List[Dict] = []
-    for node in out_nodes:
-        if (
-            merged
-            and node.get("type") == NodeType.TEXT
-            and merged[-1].get("type") == NodeType.TEXT
-            and node.get("marks") == merged[-1].get("marks")
-        ):
-            merged[-1]["text"] += node["text"]
-        else:
-            merged.append(node)
-    return merged
-
-
-def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[Dict]:
-    """Render an inline subtree into a flat list of text / anchor nodes."""
-    out: List[Dict] = []
-    for child in node.children:
-        t = child.type
-        if t == "text":
-            if child.content:
-                out.append(nodes.text(child.content, marks))
-        elif t == "code_inline":
-            out.append(nodes.text(child.content, marks + [nodes.code_mark()]))
-        elif t == "math_inline":
-            out.append(nodes.latex_inline(child.content.strip()))
-        elif t in _MARK_FOR:
-            out.extend(_render_inline(child, marks + [_MARK_FOR[t]], ctx))
-        elif t == "link":
-            href = child.attrs.get("href", "")
-            out.extend(_render_inline(child, marks + [nodes.link_mark(href)], ctx))
-        elif t in ("softbreak", "hardbreak"):
-            out.append(nodes.text(" ", marks))
-        elif t == "footnote_ref":
-            # Number anchors by document position and record which definition each
-            # one points to, so matching blocks can be emitted 1:1 afterwards.
-            ctx["order"].append(child.meta["id"])
-            out.append(nodes.footnote_anchor(len(ctx["order"])))
-        elif t == "image":
-            # Inline images are rare in this schema; fall back to alt text.
-            alt = child.attrs.get("alt") or "".join(
-                c.content for c in child.children if c.type == "text"
-            )
-            if alt:
-                out.append(nodes.text(alt, marks))
-    return _coalesce(out)
-
-
-def _only_image(inline: SyntaxTreeNode) -> Optional[SyntaxTreeNode]:
-    """If an inline node is just an image (optionally wrapped in a link), return it."""
-    kids = [c for c in inline.children if c.type != "softbreak"]
-    if len(kids) == 1 and kids[0].type == "image":
-        return kids[0]
-    if len(kids) == 1 and kids[0].type == "link":
-        inner = [c for c in kids[0].children if c.type != "softbreak"]
-        if len(inner) == 1 and inner[0].type == "image":
-            img = inner[0]
-            img._link_href = kids[0].attrs.get("href")  # type: ignore[attr-defined]
-            return img
-    return None
-
-
-def _captioned_image(img: SyntaxTreeNode, api) -> Dict:
-    src = img.attrs.get("src", "")
-    if src.startswith("/"):
-        src = src[1:]
-    if api is not None and not src.startswith("http"):
-        try:
-            src = api.get_image(src).get("url")
-        except Exception:
-            pass
-    # markdown-it stores the image alt text as the node's content, not in attrs.
-    alt = img.content or img.attrs.get("alt") or None
-    # Standard markdown image title `![alt](src "caption")` maps to Substack's caption node.
-    title = img.attrs.get("title") or None
-    caption = [nodes.text(title)] if title else None
-    return nodes.captioned_image(
-        src,
-        alt=alt,
-        href=getattr(img, "_link_href", None),
-        caption=caption,
-    )
-
-
-def _render_block(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
-    """Render a block-level node into zero or more Substack nodes."""
-    t = node.type
-
-    if t == "paragraph":
-        inline = node.children[0]
-        img = _only_image(inline)
-        if img is not None:
-            return [_captioned_image(img, api)]
-        return [nodes.paragraph(_render_inline(inline, [], ctx))]
-
-    if t == "heading":
-        level = int(node.tag[1])
-        return [nodes.heading(_render_inline(node.children[0], [], ctx), level=level)]
-
-    if t == "hr":
-        return [nodes.horizontal_rule()]
-
-    if t in ("fence", "code_block"):
-        return [
-            nodes.code_block(
-                node.content.rstrip("\n"), language=node.info.strip() or None
-            )
-        ]
-
-    if t == "blockquote":
-        paras: List[Dict] = []
-        for child in node.children:
-            paras.extend(_render_block(child, api, ctx))
-        return [nodes.blockquote(paras)]
-
-    if t == "bullet_list":
-        return [nodes.bullet_list(_render_list_items(node, api, ctx))]
-
-    if t == "ordered_list":
-        return [nodes.ordered_list(_render_list_items(node, api, ctx))]
-
-    # "$$...$$ (label)" tokenizes as math_block_label; Substack has no equation
-    # labels, so it renders like an unlabeled block.
-    if t in ("math_block", "math_block_label"):
-        return [nodes.latex_block(node.content.strip())]
-
-    if t == "container_pullquote":
-        return [nodes.pullquote(_render_container_body(node, api, ctx))]
-
-    if t == "container_callout":
-        return [nodes.callout_block(_render_container_body(node, api, ctx))]
-
-    # footnote_block is handled separately in markdown_to_doc; ignore it here.
-    return []
-
-
-def _render_container_body(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
-    body: List[Dict] = []
-    for child in node.children:
-        body.extend(_render_block(child, api, ctx))
-    return body
-
-
-def _render_list_items(list_node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
-    items = []
-    for li in list_node.children:
-        content: List[Dict] = []
-        for child in li.children:
-            content.extend(_render_block(child, api, ctx))
-        items.append({"type": NodeType.LIST_ITEM, "content": content})
-    return items
-
-
-def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]:
-    """Map each footnote id to its rendered block content."""
-    definitions: Dict[int, List[Dict]] = {}
-    for node in tree.children:
-        if node.type != "footnote_block":
-            continue
-        for fn in node.children:
-            # A footnote's own content should not register anchors of its own.
-            local_ctx = {"order": []}
-            content: List[Dict] = []
-            for child in fn.children:
-                content.extend(_render_block(child, api, local_ctx))
-            definitions[fn.meta["id"]] = content
-    return definitions
-
-
-def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
-    """Convert Markdown into a list of Substack ProseMirror block nodes."""
-    tree = SyntaxTreeNode(_make_parser().parse(markdown_content))
-
-    definitions = _footnote_definitions(tree, api)
-
-    ctx: Dict = {"order": []}
-    out: List[Dict] = []
+    if not match:
+        if "python-substack-image:v1" in clean:
+            raise ValueError("Corrupt image marker format")
+        return None
+    encoded = match.group(1)
+    encoded += "=" * (-len(encoded) % 4)
+    try:
+        attrs = json.loads(base64.urlsafe_b64decode(encoded.encode("ascii")))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    if not isinstance(attrs, dict) or any(
+        key in {"src", "alt", "href", "isProcessing"} for key in attrs
+    ):
+        raise ValueError("Invalid image marker attributes")
+    return attrs
+
+
+def _make_parser() -> MarkdownIt:
+    return (
+        MarkdownIt("commonmark")
+        .use(footnote_plugin)
+        # Pandoc-style delimiters: no whitespace just inside the dollars and no
+        # digit just outside them, so paired currency amounts ("$5 ... $10")
+        # stay plain text instead of becoming math.
+        .use(dollarmath_plugin, allow_space=False, allow_digits=False)
+        .use(sub_plugin)
+        .use(superscript_plugin)
+        .use(container_plugin, name="pullquote")
+        .use(container_plugin, name="callout")
+        .enable("strikethrough")
+    )
+
+
+def _coalesce(out_nodes: List[Dict]) -> List[Dict]:
+    """Merge adjacent text nodes that carry identical marks (e.g. softbreaks)."""
+    merged: List[Dict] = []
+    for node in out_nodes:
+        if (
+            merged
+            and node.get("type") == NodeType.TEXT
+            and merged[-1].get("type") == NodeType.TEXT
+            and node.get("marks") == merged[-1].get("marks")
+        ):
+            merged[-1]["text"] += node["text"]
+        else:
+            merged.append(node)
+    return merged
+
+
+def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[Dict]:
+    """Render an inline subtree into a flat list of text / anchor nodes."""
+    out: List[Dict] = []
+    for child in node.children:
+        t = child.type
+        if t == "text":
+            if child.content:
+                out.append(nodes.text(child.content, marks))
+        elif t == "code_inline":
+            out.append(nodes.text(child.content, marks + [nodes.code_mark()]))
+        elif t == "math_inline":
+            out.append(nodes.latex_inline(child.content.strip()))
+        elif t in _MARK_FOR:
+            out.extend(_render_inline(child, marks + [_MARK_FOR[t]], ctx))
+        elif t == "link":
+            href = child.attrs.get("href", "")
+            out.extend(_render_inline(child, marks + [nodes.link_mark(href)], ctx))
+        elif t in ("softbreak", "hardbreak"):
+            out.append(nodes.text(" ", marks))
+        elif t == "footnote_ref":
+            # Number anchors by document position and record which definition each
+            # one points to, so matching blocks can be emitted 1:1 afterwards.
+            ctx["order"].append(child.meta["id"])
+            out.append(nodes.footnote_anchor(len(ctx["order"])))
+        elif t == "image":
+            # Inline images are rare in this schema; fall back to alt text.
+            alt = child.attrs.get("alt") or "".join(
+                c.content for c in child.children if c.type == "text"
+            )
+            if alt:
+                out.append(nodes.text(alt, marks))
+        elif t == "html_inline":
+            marker_data = parse_node_marker(child.content)
+            if marker_data is not None:
+                out.append(marker_data)
+    return _coalesce(out)
+
+
+def _only_image(inline: SyntaxTreeNode) -> Optional[SyntaxTreeNode]:
+    """If an inline node is just an image (optionally wrapped in a link), return it."""
+    kids = [c for c in inline.children if c.type != "softbreak"]
+    if len(kids) == 1 and kids[0].type == "image":
+        return kids[0]
+    if len(kids) == 1 and kids[0].type == "link":
+        inner = [c for c in kids[0].children if c.type != "softbreak"]
+        if len(inner) == 1 and inner[0].type == "image":
+            img = inner[0]
+            img._link_href = kids[0].attrs.get("href")  # type: ignore[attr-defined]
+            return img
+    return None
+
+
+def _captioned_image(img: SyntaxTreeNode, api) -> Dict:
+    src = img.attrs.get("src", "")
+    if api is not None and (
+        urlsplit(src).scheme.lower() not in ("http", "https")
+        and not src.startswith("//")
+    ):
+        # Markdown destinations encode spaces and non-ASCII characters as URLs.
+        path = Path(unquote(src)).expanduser()
+        if not path.is_file() and src.startswith("/"):
+            # Preserve legacy root-relative asset paths only when they resolve
+            # to a real file; an existing absolute path always takes precedence.
+            relative = Path(unquote(src[1:]))
+            if relative.is_file():
+                path = relative
+        if not path.is_file():
+            raise FileNotFoundError(f"Local image file not found: {path}")
+        try:
+            uploaded = api.get_image(str(path))
+            url = uploaded.get("url")
+            if not isinstance(url, str) or not url.startswith(("https://", "http://")):
+                raise ValueError("Upload did not return an HTTP image URL")
+        except Exception as exc:
+            raise ValueError(f"Failed to upload local image: {path}") from exc
+        src = url
+    # markdown-it stores the image alt text as the node's content, not in attrs.
+    alt = img.content or img.attrs.get("alt") or None
+    # Standard markdown image title `![alt](src "caption")` maps to Substack's caption node.
+    title = img.attrs.get("title") or None
+    caption = [nodes.text(title)] if title else None
+    return nodes.captioned_image(
+        src,
+        alt=alt,
+        href=getattr(img, "_link_href", None),
+        caption=caption,
+    )
+
+
+def _render_block(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
+    """Render a block-level node into zero or more Substack nodes."""
+    t = node.type
+
+    if t == "html_block":
+        marker_data = parse_node_marker(node.content)
+        if marker_data is not None:
+            return [marker_data]
+        return []
+
+    if t == "paragraph":
+        inline = node.children[0]
+        img = _only_image(inline)
+        if img is not None:
+            return [_captioned_image(img, api)]
+        return [nodes.paragraph(_render_inline(inline, [], ctx))]
+
+    if t == "heading":
+        level = int(node.tag[1])
+        return [nodes.heading(_render_inline(node.children[0], [], ctx), level=level)]
+
+    if t == "hr":
+        return [nodes.horizontal_rule()]
+
+    if t in ("fence", "code_block"):
+        return [
+            nodes.code_block(
+                node.content.rstrip("\n"), language=node.info.strip() or None
+            )
+        ]
+
+    if t == "blockquote":
+        paras: List[Dict] = []
+        for child in node.children:
+            paras.extend(_render_block(child, api, ctx))
+        return [nodes.blockquote(paras)]
+
+    if t == "bullet_list":
+        return [nodes.bullet_list(_render_list_items(node, api, ctx))]
+
+    if t == "ordered_list":
+        return [nodes.ordered_list(_render_list_items(node, api, ctx))]
+
+    # "$$...$$ (label)" tokenizes as math_block_label; Substack has no equation
+    # labels, so it renders like an unlabeled block.
+    if t in ("math_block", "math_block_label"):
+        return [nodes.latex_block(node.content.strip())]
+
+    if t == "container_pullquote":
+        return [nodes.pullquote(_render_container_body(node, api, ctx))]
+
+    if t == "container_callout":
+        return [nodes.callout_block(_render_container_body(node, api, ctx))]
+
+    # footnote_block is handled separately in markdown_to_doc; ignore it here.
+    return []
+
+
+def _render_container_body(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
+    body: List[Dict] = []
+    for child in node.children:
+        body.extend(_render_block(child, api, ctx))
+    return body
+
+
+def _render_list_items(list_node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
+    items = []
+    for li in list_node.children:
+        content: List[Dict] = []
+        for child in li.children:
+            content.extend(_render_block(child, api, ctx))
+        items.append({"type": NodeType.LIST_ITEM, "content": content})
+    return items
+
+
+def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]:
+    """Map each footnote id to its rendered block content."""
+    definitions: Dict[int, List[Dict]] = {}
+    for node in tree.children:
+        if node.type != "footnote_block":
+            continue
+        for fn in node.children:
+            # A footnote's own content should not register anchors of its own.
+            local_ctx = {"order": []}
+            content: List[Dict] = []
+            for child in fn.children:
+                content.extend(_render_block(child, api, local_ctx))
+            definitions[fn.meta["id"]] = content
+    return definitions
+
+
+def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
+    """Convert Markdown into a list of Substack ProseMirror block nodes."""
+    tree = SyntaxTreeNode(_make_parser().parse(markdown_content))
+
+    definitions = _footnote_definitions(tree, api)
+
+    ctx: Dict = {"order": []}
+    out: List[Dict] = []
     for node in tree.children:
         if node.type == "footnote_block":
             continue
+        if node.type == "html_block":
+            attrs = parse_image_marker(node.content)
+            if attrs is not None:
+                if not out or out[-1].get("type") != "captionedImage":
+                    raise ValueError("Image marker must immediately follow an image")
+                out[-1]["content"][0]["attrs"].update(attrs)
+                out[-1]["content"][0]["attrs"]["isProcessing"] = False
+                continue
         out.extend(_render_block(node, api, ctx))
-
-    # Emit one footnote block per reference, in anchor order, numbered to match.
-    for number, footnote_id in enumerate(ctx["order"], start=1):
-        content = copy.deepcopy(definitions.get(footnote_id, []))
-        out.append(nodes.footnote(number, content))
-
-    return out
+
+    # Emit one footnote block per reference, in anchor order, numbered to match.
+    for number, footnote_id in enumerate(ctx["order"], start=1):
+        content = copy.deepcopy(definitions.get(footnote_id, []))
+        out.append(nodes.footnote(number, content))
+
+    return out