From 392ef20709c0c7964641c6a784a0ff0937e0db59 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 17 Nov 2026 11:27:11 +1100 Subject: [PATCH] Find local images beside the Markdown file Relative image paths in Markdown only resolved from the working directory, so `substack drafts create posts/post.md` could not find `![chart](figures/chart.png)` stored next to the post unless it was run from inside `posts/`. Add an optional `markdown_dir` argument to `markdown_to_doc`, `Post.from_markdown`, `Api.create_draft_from_markdown` and `Api.update_draft_from_markdown`. A relative image path that is not found in the working directory is then looked up in that folder. The draft commands pass the Markdown file's folder. The working directory is still checked first, so every path that resolves today resolves to the same file. Co-Authored-By: Claude --- CHANGELOG.md | 8 ++ docs/cli.md | 5 + docs/markdown.md | 5 +- docs/troubleshooting.md | 5 +- docs/yaml.md | 4 + substack/api.py | 20 +++- substack/cli.py | 6 + substack/mdrender.py | 32 ++++-- substack/post.py | 9 +- tests/substack/test_cli.py | 45 ++++++++ tests/substack/test_cli_operations.py | 1 + tests/substack/test_cli_update.py | 12 ++ tests/substack/test_local_markdown_images.py | 113 +++++++++++++++++++ 13 files changed, 251 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f9d4a60..bd1d483 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,14 @@ (confirmed by applying both to a live draft and reading the rendered HTML back: `textStyle` becomes a `` with inline `color`, `highlight` becomes a `` with inline `background-color`). +- Optional `markdown_dir` argument on `Post.from_markdown`, + `Api.create_draft_from_markdown`, `Api.update_draft_from_markdown`, and + `mdrender.markdown_to_doc`. A relative local image path that is not found in + the working directory is then looked up in that folder. The `substack drafts + create`, `substack drafts update`, `substack-publish-markdown`, and + `substack-publish-yaml` commands pass the Markdown file's folder (the YAML + file's folder for inline Markdown), so images stored beside a post are found + from any working directory. Paths that resolve today resolve to the same file. ### Fixed diff --git a/docs/cli.md b/docs/cli.md index 946bb8e..083241b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -17,6 +17,11 @@ substack drafts create post.md The title comes from the first Markdown heading, then the filename if the file has no heading. Use `--title` to override it. +Relative local image paths resolve from the current working directory. An +image that is not found there is also looked up in the Markdown file's folder, +so `substack drafts create posts/post.md` finds `![chart](figures/chart.png)` +at `posts/figures/chart.png`. `substack drafts update` does the same. + ## Export a draft to Markdown Print a read-only Markdown backup to standard output: diff --git a/docs/markdown.md b/docs/markdown.md index 25728c5..ca33460 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -128,7 +128,10 @@ A paragraph containing only an image becomes a captioned image. Absolute paths are preserved, `~` expands to the user's home directory, and relative paths resolve from the current working directory. A leading `/` is removed only as a legacy fallback when the absolute file does not exist and - the corresponding relative file does. Missing files and failed uploads raise + the corresponding relative file does. A relative path that is not found in + the working directory is also looked up in the Markdown file's folder when + that folder is known: the CLI passes it automatically, and Python callers + can pass `markdown_dir=`. Missing files and failed uploads raise an error naming the file instead of silently saving a broken image. PNG, JPEG, GIF, and WebP are uploaded without conversion, including animations. HTTP(S) and protocol-relative URLs remain unchanged. Without `api=`, image diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d8e2ec5..0843fd5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -46,7 +46,10 @@ checking the draft ID. Pass the authenticated `Api` instance to `Post.from_markdown(..., api=api)` or use `Api.create_draft_from_markdown`, which does this automatically. Relative image paths resolve from the current working directory; absolute paths are -preserved and `~` expands to the current user's home directory. HTTP(S) and +preserved and `~` expands to the current user's home directory. A relative +path that is not found there is also looked up in the Markdown file's folder: +the CLI does this automatically, and Python callers can pass +`markdown_dir=Path("posts")` alongside the Markdown text. HTTP(S) and protocol-relative image URLs are not uploaded. Missing files and failed uploads name the affected path instead of silently retaining a broken source. diff --git a/docs/yaml.md b/docs/yaml.md index b9a0b02..1093b45 100644 --- a/docs/yaml.md +++ b/docs/yaml.md @@ -34,6 +34,10 @@ markdown_file: "post.md" Relative Markdown paths resolve from the YAML file's directory. +Relative local image paths resolve from the current working directory. An +image that is not found there is also looked up in the Markdown file's folder, +or in the YAML file's folder when the Markdown is inline. + The lower-level node form remains supported: ```yaml diff --git a/substack/api.py b/substack/api.py index 467347c..61d7c77 100644 --- a/substack/api.py +++ b/substack/api.py @@ -506,9 +506,14 @@ def update_draft_from_markdown( expected_revision=None, allow_conflict: bool = False, force: bool = False, + markdown_dir=None, ) -> dict: """ Update an existing draft body from Markdown, with optional metadata changes. + + ``markdown_dir`` is the folder of the file the Markdown came from. A + relative local image path that is not found in the working directory + is then looked up in that folder. """ from substack import mdrender from substack.exceptions import DraftConflictError @@ -589,7 +594,10 @@ def update_draft_from_markdown( write_comment_permissions=write_comment_permissions, ) rendered = mdrender.markdown_to_doc( - markdown, api=self, track_markers=image_markers + markdown, + api=self, + track_markers=image_markers, + markdown_dir=markdown_dir, ) post.draft_body["content"] = rendered @@ -775,7 +783,15 @@ def create_draft_from_markdown( publish: bool = False, send: bool = True, share_automatically: bool = False, + markdown_dir=None, ) -> dict: + """ + Create a draft from Markdown. + + ``markdown_dir`` is the folder of the file the Markdown came from. A + relative local image path that is not found in the working directory + is then looked up in that folder. + """ from substack.post import Post post = Post( @@ -785,7 +801,7 @@ def create_draft_from_markdown( audience=audience, write_comment_permissions=write_comment_permissions, ) - post.from_markdown(markdown, api=self) + post.from_markdown(markdown, api=self, markdown_dir=markdown_dir) draft = self.post_draft(post.get_draft()) draft_id = draft.get("id") diff --git a/substack/cli.py b/substack/cli.py index 23109cf..ba96612 100644 --- a/substack/cli.py +++ b/substack/cli.py @@ -307,6 +307,7 @@ def _drafts_create(api, args): tags=args.tags, prepublish=False, publish=False, + markdown_dir=markdown_path.parent, ) draft = result["draft"] payload = { @@ -369,6 +370,7 @@ def _drafts_update(api, args): allow_unsupported_change=args.allow_unsupported_change, allow_image_replacement=args.allow_image_replacement, allow_conflict=args.allow_conflict, + markdown_dir=markdown_file.parent, ) if args.json_output: @@ -648,6 +650,7 @@ def publish_markdown(argv=None): publish=args.publish, send=args.send, share_automatically=args.share_automatically, + markdown_dir=markdown_path.parent, ) _print_result(result) return 0 @@ -669,12 +672,14 @@ def publish_yaml(argv=None): api = _api_from_env(args.cookies) markdown = post_data.get("markdown") + markdown_dir = post_path.parent markdown_file = post_data.get("markdown_file") if markdown_file: markdown_path = Path(markdown_file) if not markdown_path.is_absolute(): markdown_path = post_path.parent / markdown_path markdown = markdown_path.read_text(encoding="utf-8") + markdown_dir = markdown_path.parent if markdown is not None: result = api.create_draft_from_markdown( @@ -694,6 +699,7 @@ def publish_yaml(argv=None): publish=args.publish, send=args.send, share_automatically=args.share_automatically, + markdown_dir=markdown_dir, ) _print_result(result) return 0 diff --git a/substack/mdrender.py b/substack/mdrender.py index 355889f..1663d48 100644 --- a/substack/mdrender.py +++ b/substack/mdrender.py @@ -250,7 +250,7 @@ def _only_image(inline: SyntaxTreeNode) -> Optional[SyntaxTreeNode]: return None -def _captioned_image(img: SyntaxTreeNode, api) -> Dict: +def _captioned_image(img: SyntaxTreeNode, api, markdown_dir=None) -> Dict: src = img.attrs.get("src", "") if api is not None and ( urlsplit(src).scheme.lower() not in ("http", "https") @@ -264,6 +264,12 @@ def _captioned_image(img: SyntaxTreeNode, api) -> Dict: relative = Path(unquote(src[1:])) if relative.is_file(): path = relative + if not path.is_file() and markdown_dir is not None: + # A relative path that is not in the working directory may be + # relative to the Markdown file it was written in. + beside_markdown = Path(markdown_dir) / path + if beside_markdown.is_file(): + path = beside_markdown if not path.is_file(): raise FileNotFoundError(f"Local image file not found: {path}") try: @@ -301,7 +307,7 @@ def _render_block(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]: inline = node.children[0] img = _only_image(inline) if img is not None: - return [_captioned_image(img, api)] + return [_captioned_image(img, api, ctx.get("markdown_dir"))] return [nodes.paragraph(_render_inline(inline, [], ctx))] if t == "heading": @@ -362,7 +368,9 @@ def _render_list_items(list_node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]: return items -def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]: +def _footnote_definitions( + tree: SyntaxTreeNode, api, markdown_dir=None +) -> Dict[int, List[Dict]]: """Map each footnote id to its rendered block content.""" definitions: Dict[int, List[Dict]] = {} for node in tree.children: @@ -370,7 +378,7 @@ def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]: continue for fn in node.children: # A footnote's own content should not register anchors of its own. - local_ctx = {"order": []} + local_ctx = {"order": [], "markdown_dir": markdown_dir} content: List[Dict] = [] for child in fn.children: content.extend(_render_block(child, api, local_ctx)) @@ -379,14 +387,22 @@ def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]: def markdown_to_doc( - markdown_content: str, api=None, track_markers: Optional[List] = None + markdown_content: str, + api=None, + track_markers: Optional[List] = None, + markdown_dir=None, ) -> List[Dict]: - """Convert Markdown into a list of Substack ProseMirror block nodes.""" + """Convert Markdown into a list of Substack ProseMirror block nodes. + + ``markdown_dir`` is the folder of the file the Markdown came from. A + relative local image path that is not found in the working directory is + then looked up in that folder. + """ tree = SyntaxTreeNode(_make_parser().parse(markdown_content)) - definitions = _footnote_definitions(tree, api) + definitions = _footnote_definitions(tree, api, markdown_dir) - ctx: Dict = {"order": []} + ctx: Dict = {"order": [], "markdown_dir": markdown_dir} out: List[Dict] = [] last_was_image = False last_image_idx: Optional[int] = None diff --git a/substack/post.py b/substack/post.py index 1d58385..e35644c 100644 --- a/substack/post.py +++ b/substack/post.py @@ -593,7 +593,7 @@ def footnote(self, number: int, content=None): self.draft_body["content"] = self.draft_body.get("content", []) + [node] return self - def from_markdown(self, markdown_content: str, api=None): + def from_markdown(self, markdown_content: str, api=None, markdown_dir=None): """ Parse Markdown content and add it to the post. @@ -618,6 +618,9 @@ def from_markdown(self, markdown_content: str, api=None): markdown_content: Markdown string to parse and add to the post. api: Optional Api instance for uploading local images. If provided, local image paths will be uploaded via api.get_image(). + markdown_dir: Optional folder of the file the Markdown came from. + A relative local image path that is not found in the working + directory is then looked up in this folder. Returns: Self for method chaining. @@ -628,6 +631,8 @@ def from_markdown(self, markdown_content: str, api=None): """ from substack import mdrender - rendered = mdrender.markdown_to_doc(markdown_content, api=api) + rendered = mdrender.markdown_to_doc( + markdown_content, api=api, markdown_dir=markdown_dir + ) self.draft_body["content"] = self.draft_body.get("content", []) + rendered return self diff --git a/tests/substack/test_cli.py b/tests/substack/test_cli.py index 1926879..0660b35 100644 --- a/tests/substack/test_cli.py +++ b/tests/substack/test_cli.py @@ -100,3 +100,48 @@ def test_auth_method_reads_env(monkeypatch): monkeypatch.setenv("COOKIES_STRING", "substack.sid=value") assert cli._auth_method() == "cookies_string" + + +def test_publish_markdown_passes_markdown_folder_for_local_images( + tmp_path, monkeypatch, capsys +): + markdown = tmp_path / "posts" / "post.md" + markdown.parent.mkdir() + markdown.write_text("# Title\n\nBody", encoding="utf-8") + api = FakeApi() + monkeypatch.setattr(cli, "_api_from_env", lambda cookies_path=None: api) + + assert cli.publish_markdown([str(markdown)]) == 0 + + assert api.kwargs["markdown_dir"] == markdown.parent + + +def test_publish_yaml_passes_markdown_file_folder_for_local_images( + tmp_path, monkeypatch, capsys +): + markdown = tmp_path / "posts" / "post.md" + markdown.parent.mkdir() + markdown.write_text("Body", encoding="utf-8") + post = tmp_path / "draft.yaml" + post.write_text("title: Title\nmarkdown_file: posts/post.md\n", encoding="utf-8") + api = FakeApi() + monkeypatch.setattr(cli, "_api_from_env", lambda cookies_path=None: api) + + assert cli.publish_yaml([str(post)]) == 0 + + assert api.kwargs["markdown"] == "Body" + assert api.kwargs["markdown_dir"] == markdown.parent + + +def test_publish_yaml_passes_yaml_folder_for_inline_markdown( + tmp_path, monkeypatch, capsys +): + post = tmp_path / "drafts" / "draft.yaml" + post.parent.mkdir() + post.write_text("title: Title\nmarkdown: Body\n", encoding="utf-8") + api = FakeApi() + monkeypatch.setattr(cli, "_api_from_env", lambda cookies_path=None: api) + + assert cli.publish_yaml([str(post)]) == 0 + + assert api.kwargs["markdown_dir"] == post.parent diff --git a/tests/substack/test_cli_operations.py b/tests/substack/test_cli_operations.py index 32788be..2c40cc2 100644 --- a/tests/substack/test_cli_operations.py +++ b/tests/substack/test_cli_operations.py @@ -188,6 +188,7 @@ def test_drafts_create_infers_title_and_preserves_safe_defaults( assert kwargs == { "title": "Inferred title", "markdown": "# Inferred title\n\nBody", + "markdown_dir": tmp_path, "subtitle": "", "audience": "everyone", "write_comment_permissions": "everyone", diff --git a/tests/substack/test_cli_update.py b/tests/substack/test_cli_update.py index 5e82cb1..75e7393 100644 --- a/tests/substack/test_cli_update.py +++ b/tests/substack/test_cli_update.py @@ -169,3 +169,15 @@ def test_drafts_update_passes_force_as_allow_conflict(tmp_path, monkeypatch, cap assert api.calls[0][0] == "update" assert api.calls[0][1] == 42 assert api.calls[0][3]["allow_conflict"] is True + + +def test_drafts_update_passes_markdown_folder_for_local_images( + tmp_path, monkeypatch, capsys +): + api = UpdateOperationsApi() + use_api(monkeypatch, api) + md_file = tmp_path / "posts" / "test.md" + md_file.parent.mkdir() + md_file.write_text("# Test", encoding="utf-8") + assert cli.main(["drafts", "update", "42", str(md_file), "--yes"]) == 0 + assert api.calls[0][3]["markdown_dir"] == md_file.parent diff --git a/tests/substack/test_local_markdown_images.py b/tests/substack/test_local_markdown_images.py index 1fb7859..bb330f5 100644 --- a/tests/substack/test_local_markdown_images.py +++ b/tests/substack/test_local_markdown_images.py @@ -1,6 +1,7 @@ """Offline regression tests for Markdown local-image uploads.""" import os +from pathlib import Path from unittest.mock import Mock import pytest @@ -124,3 +125,115 @@ def test_remote_url_unchanged(api, src): ) def test_without_api_retains_source(src): assert render(src) == src + + +@pytest.fixture +def post_dir(tmp_path, monkeypatch): + """A Markdown file's folder that is not the working directory.""" + cwd = tmp_path / "cwd" + cwd.mkdir() + monkeypatch.chdir(cwd) + folder = tmp_path / "posts" / "first post" + (folder / "figures").mkdir(parents=True) + return folder + + +def render_from(markdown, api, markdown_dir): + post = Post(title="Image test", subtitle="", user_id=1) + post.from_markdown(markdown, api=api, markdown_dir=markdown_dir) + return post.draft_body["content"] + + +@pytest.mark.parametrize("as_type", [str, lambda path: path]) +def test_relative_file_found_beside_markdown(api, post_dir, as_type): + image = post_dir / "figures" / "obraz żółty.png" + image.touch() + content = render_from("![alt]()", api, as_type(post_dir)) + assert content[0]["content"][0]["attrs"]["src"] == UPLOADED + api.get_image.assert_called_once_with(str(image)) + + +@pytest.mark.parametrize( + "markdown", + [ + "> ![alt](figures/chart.png)", + "- ![alt](figures/chart.png)", + "1. Item\n\n ![alt](figures/chart.png)", + ":::callout\n![alt](figures/chart.png)\n:::", + "Text.[^note]\n\n[^note]: ![alt](figures/chart.png)", + ], +) +def test_nested_relative_file_found_beside_markdown(api, post_dir, markdown): + image = post_dir / "figures" / "chart.png" + image.touch() + render_from(markdown, api, post_dir) + api.get_image.assert_called_once_with(str(image)) + + +def test_working_directory_takes_priority_over_markdown_folder(api, post_dir): + (post_dir / "image.png").touch() + Path("image.png").touch() + render_from("![alt](image.png)", api, post_dir) + api.get_image.assert_called_once_with("image.png") + + +def test_file_missing_from_both_folders_fails_before_upload(api, post_dir): + with pytest.raises(FileNotFoundError) as error: + render_from("![alt](figures/missing.png)", api, post_dir) + # The message names the path as written, as it does without markdown_dir. + written = Path("figures/missing.png") + assert str(error.value) == f"Local image file not found: {written}" + api.get_image.assert_not_called() + + +@pytest.mark.parametrize("src", ["/image.png", "~/image.png"]) +def test_rooted_and_home_paths_ignore_markdown_folder( + tmp_path, monkeypatch, api, post_dir, src +): + monkeypatch.setenv("HOME", str(tmp_path / "home")) + monkeypatch.setenv("USERPROFILE", str(tmp_path / "home")) + (post_dir / "image.png").touch() + with pytest.raises(FileNotFoundError): + render_from(f"![alt]({src})", api, post_dir) + api.get_image.assert_not_called() + + +def test_directory_beside_markdown_is_not_an_image(api, post_dir): + with pytest.raises(FileNotFoundError): + render_from("![alt](figures)", api, post_dir) + api.get_image.assert_not_called() + + +def test_remote_url_ignores_markdown_folder(api, post_dir): + content = render_from("![alt](https://example.com/a.png)", api, post_dir) + assert content[0]["content"][0]["attrs"]["src"] == "https://example.com/a.png" + api.get_image.assert_not_called() + + +def test_create_draft_from_markdown_finds_file_beside_markdown(api, post_dir): + image = post_dir / "figures" / "chart.png" + image.touch() + api.get_user_id = Mock(return_value=1) + api.post_draft = Mock(return_value={"id": 123}) + api.create_draft_from_markdown( + title="Title", markdown="![alt](figures/chart.png)", markdown_dir=post_dir + ) + api.get_image.assert_called_once_with(str(image)) + + +def test_update_draft_from_markdown_finds_file_beside_markdown(api, post_dir): + image = post_dir / "figures" / "chart.png" + image.touch() + api.get_user_id = Mock(return_value=1) + api.get_draft = Mock( + return_value={"id": 42, "draft_body": '{"type":"doc","content":[]}'} + ) + api.put_draft = Mock(return_value={"id": 42}) + api.update_draft_from_markdown( + 42, + "![alt](figures/chart.png)", + allow_conflict=True, + allow_image_replacement=True, + markdown_dir=post_dir, + ) + api.get_image.assert_called_once_with(str(image))