release: prepare 0.6.0

Author: ma2za

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- Add read-only `Api.export_draft_to_markdown(draft_id)` with the original draft, exported Markdown, and unsupported-node details.
+- Add `substack drafts export DRAFT_ID`, including stable JSON output and safe `--output` and `--force` file handling.
+- Reverse-render every Substack node supported by Markdown import, including formatting, nested lists, images and captions, code languages, footnotes, math, pull quotes, and callouts.
+- Preserve unsupported nodes and unknown fields as versioned, decodable `python-substack-node:v1` markers instead of silently dropping them.
+
 ## 0.5.0
 
 ### Added

README.md

@@ -57,6 +57,7 @@ Substack result:
 - Upload local images referenced by Markdown.
 - 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.
 - 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.
@@ -107,6 +108,7 @@ Inspect publications and drafts:
 substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
+substack drafts export 12345 --output backup.md
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -171,6 +173,14 @@ print(result["draft"]["id"])
 `create_draft_from_markdown` creates a draft by default. It publishes only when
 `publish=True` is passed.
 
+Back up an existing draft without modifying it:
+
+```python
+backup = api.export_draft_to_markdown(12345)
+print(backup["markdown"])
+print(backup["unsupported_nodes"])
+```
+
 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).

docs/cli.md

@@ -17,6 +17,25 @@ 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.
 
+## Export a draft to Markdown
+
+Print a read-only Markdown backup to standard output:
+
+```bash
+substack drafts export 12345
+```
+
+Write it to a UTF-8 file:
+
+```bash
+substack drafts export 12345 --output backup.md
+```
+
+The command refuses to replace an existing file unless `--force` is present.
+It fetches the draft but performs no server writes. Content without a supported
+Markdown representation is emitted as a versioned opaque HTML comment instead
+of being silently discarded.
+
 ## Select a publication
 
 List every publication available to the authenticated account:
@@ -49,10 +68,13 @@ substack drafts unschedule 12345
 
 ```bash
 substack --json drafts list --limit 10
+substack --json drafts export 12345
 ```
 
 The command writes a JSON object containing `drafts`, `count`, `filter`,
 `offset`, and `limit`. Errors are also JSON when `--json` is present.
+Export JSON contains `action`, `draft_id`, `markdown`, and
+`unsupported_nodes`.
 
 ## Publish and delete
 

docs/markdown.md

@@ -173,3 +173,25 @@ document remains valid. Unknown `:::` container names remain ordinary text.
   and add it in the Substack editor.
 - Widgets authored only in the Substack editor (buttons, polls, embeds, etc.)
   have no Markdown equivalent.
+
+## Draft export and opaque nodes
+
+`Api.export_draft_to_markdown(draft_id)` and `substack drafts export DRAFT_ID`
+reverse supported Substack nodes into Markdown. The export is read-only and
+returns every unsupported node separately in `unsupported_nodes`.
+
+Unsupported nodes and supported nodes with unknown fields are also kept at
+their document position as:
+
+```text
+<!-- python-substack-node:v1 BASE64URL_JSON -->
+```
+
+The payload is UTF-8 JSON encoded with URL-safe base64 and no padding. This
+makes unsupported content visible and recoverable instead of silently dropping
+it. Version 0.6 does not import these markers into a draft; safe updates that
+preserve them are planned for 0.8.
+
+Export preserves the Markdown meaning of supported images: source, alt text,
+link, and plain-text caption. Substack-only image layout attributes are not a
+Markdown contract in 0.6.

docs/python-sdk.md

@@ -35,5 +35,21 @@ The method creates an unpublished draft by default. It publishes only when
 `publish=True` is passed. It can also set audience, comment permissions, SEO
 metadata, slug, section, and tags.
 
+## Export a draft without modifying it
+
+```python
+from pathlib import Path
+
+result = api.export_draft_to_markdown(12345)
+
+Path("backup.md").write_text(result["markdown"], encoding="utf-8")
+print(result["unsupported_nodes"])
+```
+
+The result contains the original `draft`, exported `markdown`, and an
+`unsupported_nodes` list. The method performs one draft read and no server
+writes. Unsupported editor nodes remain embedded in the Markdown as opaque,
+decodable markers.
+
 For supported syntax, see the [Markdown reference](markdown.md). For direct
 editor-node construction, see the [low-level Python API](low-level-api.md).

docs/releases/0.6.0.md

@@ -0,0 +1,56 @@
+---
+layout: default
+title: 0.6.0
+parent: Releases
+nav_order: 6
+---
+
+# 0.6.0 Release
+
+Version 0.6.0 adds loss-aware, read-only backups of Substack drafts as
+Markdown.
+
+## Export from the CLI
+
+Print a draft as Markdown without changing it on Substack:
+
+```bash
+substack drafts export 12345
+```
+
+Write a UTF-8 backup file, refusing accidental replacement by default:
+
+```bash
+substack drafts export 12345 --output backup.md
+substack drafts export 12345 --output backup.md --force
+```
+
+Global JSON mode returns `action`, `draft_id`, `markdown`, and
+`unsupported_nodes`.
+
+## Export from Python
+
+```python
+result = api.export_draft_to_markdown(12345)
+markdown = result["markdown"]
+unsupported = result["unsupported_nodes"]
+```
+
+The method performs one draft read and no server writes.
+
+## Loss-aware rendering
+
+Export preserves the semantic Markdown content supported by import, including
+headings, text marks, links, nested lists, images, captions, code languages,
+blockquotes, footnotes, math, pull quotes, and callouts.
+
+Substack editor nodes without a supported Markdown representation remain at
+their document position as versioned URL-safe base64 JSON markers:
+
+```text
+<!-- python-substack-node:v1 BASE64URL_JSON -->
+```
+
+They are also returned in `unsupported_nodes`, making unsupported content
+visible and recoverable rather than silently discarding it. Version 0.6 does
+not import opaque markers back into a draft.

docs/safety.md

@@ -9,6 +9,7 @@ Creating, scheduling, publishing, and deleting are separate operations.
 
 | Operation | Effect | Confirmation |
 |---|---|---|
+| `drafts export` | Reads a draft and produces Markdown | None |
 | `drafts create` | Creates an unpublished draft | None |
 | `drafts schedule` | Adds a future release time | None |
 | `drafts unschedule` | Removes a future release time | None |
@@ -26,3 +27,7 @@ before they are printed by the CLI.
 Substack's interfaces are undocumented and may change. Keep a reviewed copy of
 important source Markdown and verify the selected publication with
 `substack status` before any write.
+
+Export never writes to Substack and never overwrites a local file unless
+`--force` is supplied. Unsupported editor content is preserved as an opaque
+marker and listed in JSON output so it cannot disappear unnoticed.

pyproject.toml

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

substack/__init__.py

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

substack/api.py

@@ -442,6 +442,28 @@ def get_draft(self, draft_id):
         response = self._session.get(f"{self.publication_url}/drafts/{draft_id}")
         return Api._handle_response(response=response)
 
+    def export_draft_to_markdown(self, draft_id):
+        from substack.mdexport import document_to_markdown
+
+        draft = self.get_draft(draft_id)
+        draft_body = draft.get("draft_body")
+        if isinstance(draft_body, str):
+            try:
+                draft_body = json.loads(draft_body)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    "Malformed draft body: draft_body is not valid JSON"
+                ) from exc
+        if not isinstance(draft_body, dict):
+            raise ValueError("Malformed draft body: draft_body must be a JSON object")
+
+        markdown, unsupported_nodes = document_to_markdown(draft_body)
+        return {
+            "draft": draft,
+            "markdown": markdown,
+            "unsupported_nodes": unsupported_nodes,
+        }
+
     def delete_draft(self, draft_id):
         """