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))