Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@
(confirmed by applying both to a live draft and reading the rendered HTML
back: `textStyle` becomes a `<span data-color>` with inline `color`,
`highlight` becomes a `<mark data-color>` 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

Expand Down
5 changes: 5 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
5 changes: 4 additions & 1 deletion docs/markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 4 additions & 0 deletions docs/yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 18 additions & 2 deletions substack/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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(
Expand All @@ -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")
Expand Down
6 changes: 6 additions & 0 deletions substack/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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(
Expand All @@ -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
Expand Down
32 changes: 24 additions & 8 deletions substack/mdrender.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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:
Expand Down Expand Up @@ -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":
Expand Down Expand Up @@ -362,15 +368,17 @@ 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:
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": []}
local_ctx = {"order": [], "markdown_dir": markdown_dir}
content: List[Dict] = []
for child in fn.children:
content.extend(_render_block(child, api, local_ctx))
Expand All @@ -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
Expand Down
9 changes: 7 additions & 2 deletions substack/post.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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
45 changes: 45 additions & 0 deletions tests/substack/test_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
1 change: 1 addition & 0 deletions tests/substack/test_cli_operations.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
12 changes: 12 additions & 0 deletions tests/substack/test_cli_update.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading
Loading