Skip to content

Commit 601a24b

Browse files
ma2zama2za
committed
Prepare python-substack 0.3.0
1 parent 991ed9b commit 601a24b

25 files changed

Lines changed: 532 additions & 2 deletions

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# Changelog
22

3+
## 0.3.0
4+
5+
### Added
6+
7+
- GitHub Pages documentation with a task-oriented index for installation,
8+
authentication, CLI, Python, Markdown, MCP, safety, and troubleshooting.
9+
- A five-minute Markdown-to-unpublished-draft walkthrough using the existing
10+
before and after images.
11+
- Tested examples for draft creation, scheduling, publication selection,
12+
stable JSON automation, and cookie authentication verification.
13+
- A documentation project link in package metadata and repository navigation.
14+
15+
### Improved
16+
17+
- Add Jekyll front matter to existing documentation while preserving every
18+
previous documentation path.
19+
- Keep creating, scheduling, publishing, and deleting clearly separated in the
20+
onboarding and safety guides.
21+
22+
No runtime interface changed in this release.
23+
324
## 0.2.0
425

526
### Added

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ publish them through Python, a command-line interface, or MCP.
1010
[![License](https://img.shields.io/pypi/l/python-substack)](LICENSE)
1111
[![Downloads](https://static.pepy.tech/badge/python-substack/month)](https://pepy.tech/project/python-substack)
1212

13+
[Documentation](https://ma2za.github.io/python-substack/) ·
14+
[Getting started](https://ma2za.github.io/python-substack/getting-started.html) ·
15+
[PyPI](https://pypi.org/project/python-substack/)
16+
1317
> [!IMPORTANT]
1418
> Creating and publishing are separate operations. `substack drafts create`
1519
> always creates an unpublished draft. It never schedules, sends, publishes,
@@ -213,12 +217,18 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
213217

214218
## Project documentation
215219

220+
- [Documentation site](https://ma2za.github.io/python-substack/)
221+
- [Installation and first draft](docs/getting-started.md)
222+
- [Unified CLI](docs/cli.md)
223+
- [Python SDK](docs/python-sdk.md)
216224
- [Authentication](docs/authentication.md)
217225
- [Markdown reference](docs/markdown.md)
218226
- [Legacy CLI commands](docs/legacy-cli.md)
219227
- [Low-level Python API](docs/low-level-api.md)
220228
- [YAML drafts](docs/yaml.md)
221229
- [MCP server](docs/mcp.md)
230+
- [Safety and publishing behavior](docs/safety.md)
231+
- [Troubleshooting](docs/troubleshooting.md)
222232
- [Compatibility policy](docs/compatibility.md)
223233
- [Contributing](CONTRIBUTING.md)
224234
- [Security policy](SECURITY.md)

‎docs/_config.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
title: python-substack
2+
description: Safe Substack draft automation from Markdown with Python, CLI, and MCP.
3+
theme: jekyll-theme-minimal
4+
plugins:
5+
- jekyll-relative-links
6+
relative_links:
7+
enabled: true
8+
collections: true
9+
include:
10+
- README.md

‎docs/authentication.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: Authentication
4+
---
5+
16
# Authentication
27

38
python-substack accepts email and password credentials, a cookies JSON file, or

‎docs/cli.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
layout: default
3+
title: Unified CLI
4+
---
5+
6+
# Unified CLI
7+
8+
Global options such as `--json`, `--cookies`, and `--publication-url` must
9+
appear before the command.
10+
11+
## Create an unpublished draft
12+
13+
```bash
14+
substack drafts create post.md
15+
```
16+
17+
The title comes from the first Markdown heading, then the filename if the file
18+
has no heading. Use `--title` to override it.
19+
20+
## Select a publication
21+
22+
List every publication available to the authenticated account:
23+
24+
```bash
25+
substack publications list
26+
```
27+
28+
Select one for a single command:
29+
30+
```bash
31+
substack --publication-url https://example.substack.com drafts list
32+
```
33+
34+
## Schedule an existing draft
35+
36+
Pass an ISO 8601 timestamp with a timezone offset or `Z`:
37+
38+
```bash
39+
substack drafts schedule 12345 --at 2030-01-02T09:00:00+01:00
40+
```
41+
42+
Remove the schedule without deleting the draft:
43+
44+
```bash
45+
substack drafts unschedule 12345
46+
```
47+
48+
## Stable JSON for automation
49+
50+
```bash
51+
substack --json drafts list --limit 10
52+
```
53+
54+
The command writes a JSON object containing `drafts`, `count`, `filter`,
55+
`offset`, and `limit`. Errors are also JSON when `--json` is present.
56+
57+
## Publish and delete
58+
59+
```bash
60+
substack drafts publish 12345 --no-send
61+
substack drafts delete 12345 --yes
62+
```
63+
64+
Publishing and deletion require confirmation. JSON and noninteractive
65+
workflows must pass `--yes`. Publishing runs Substack's prepublish check first.
66+
See [safety and publishing behavior](safety.md).
67+
68+
The original console scripts remain supported. See
69+
[legacy CLI commands](legacy-cli.md).

‎docs/compatibility.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: Compatibility policy
4+
---
5+
16
# Compatibility policy
27

38
python-substack preserves its established public interfaces while progressing

‎docs/getting-started.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
layout: default
3+
title: Installation and first draft
4+
---
5+
6+
# Installation and first draft
7+
8+
This is the shortest path from a Markdown file to a safe unpublished Substack
9+
draft.
10+
11+
## 1. Install
12+
13+
```bash
14+
python -m pip install python-substack
15+
substack --version
16+
```
17+
18+
## 2. Authenticate
19+
20+
Create a `.env` file in your working directory. Cookie authentication is
21+
usually the most reliable option:
22+
23+
```env
24+
COOKIES_PATH=cookies.json
25+
PUBLICATION_URL=https://example.substack.com
26+
```
27+
28+
See [authentication and cookies](authentication.md) for browser-cookie export,
29+
password authentication, and secret-handling guidance.
30+
31+
Confirm the selected account and publication:
32+
33+
```bash
34+
substack status
35+
```
36+
37+
## 3. Write Markdown
38+
39+
Save this as `first-draft.md`:
40+
41+
```markdown
42+
# My first automated draft
43+
44+
This draft was created from **Markdown**.
45+
46+
- Review it in Substack.
47+
- Publish only when it is ready.
48+
```
49+
50+
Markdown source:
51+
52+
![Markdown before conversion](before.png)
53+
54+
Rendered in Substack:
55+
56+
![Substack after conversion](after.png)
57+
58+
## 4. Create the draft
59+
60+
```bash
61+
substack drafts create first-draft.md
62+
```
63+
64+
`drafts create` always creates an unpublished draft. It never schedules,
65+
sends, publishes, or deletes content. Open the returned draft ID in Substack
66+
and review it there.
67+
68+
Continue with the [unified CLI guide](cli.md) or use the
69+
[Python SDK](python-sdk.md).

‎docs/index.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: default
3+
title: python-substack documentation
4+
---
5+
6+
# python-substack documentation
7+
8+
Create, inspect, schedule, and publish Substack drafts from Markdown through
9+
Python, a command-line interface, or MCP.
10+
11+
Start with [installation and your first draft](getting-started.md). The final
12+
command in that guide creates an unpublished draft and does not schedule, send,
13+
publish, or delete it.
14+
15+
## Guides
16+
17+
- [Installation and first draft](getting-started.md)
18+
- [Authentication and cookies](authentication.md)
19+
- [Unified CLI](cli.md)
20+
- [Python SDK](python-sdk.md)
21+
- [Markdown syntax](markdown.md)
22+
- [MCP setup](mcp.md)
23+
- [Safety and publishing behavior](safety.md)
24+
- [Troubleshooting](troubleshooting.md)
25+
26+
## More documentation
27+
28+
- [Legacy CLI commands](legacy-cli.md)
29+
- [Low-level Python API](low-level-api.md)
30+
- [YAML drafts](yaml.md)
31+
- [Compatibility policy](compatibility.md)
32+
- [Changelog](https://github.com/ma2za/python-substack/blob/main/CHANGELOG.md)
33+
- [Release roadmap](https://github.com/ma2za/python-substack/blob/main/ROADMAP.md)

‎docs/legacy-cli.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: Legacy CLI commands
4+
---
5+
16
# Legacy CLI commands
27

38
The original standalone console commands remain supported for compatibility.

‎docs/low-level-api.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: Low-level Python API
4+
---
5+
16
# Low-level Python API
27

38
Most callers should use `Api.create_draft_from_markdown`. The `Post` builder is

0 commit comments

Comments
 (0)