diff --git a/custom-skills/32-notion-writer/SKILL.md b/custom-skills/32-notion-writer/SKILL.md index 3c74555..18604b1 100644 --- a/custom-skills/32-notion-writer/SKILL.md +++ b/custom-skills/32-notion-writer/SKILL.md @@ -139,6 +139,19 @@ python notion_writer.py -d DATABASE_URL -t "Entry Title" -f content.md | `---` | Divider | | Paragraphs | Paragraph | +### Engines and image uploads + +Two write engines via `--engine {blocks,markdown}` (default: `blocks`). + +The **blocks engine** (default) converts markdown locally to Notion block objects. Local images (`![alt](./file.png)`) are auto-uploaded via the `ntn` CLI and embedded at their original position in the page. Requires `ntn` installed and `ntn login`. + +The **markdown engine** (`--engine markdown`) posts the document through Notion's native enhanced-markdown API (`Notion-Version: 2026-03-11`, set automatically; override with `--notion-version`). The skill's authoring dialect — GitHub alerts (`[!NOTE]`), Pandoc columns (`::: columns`), `
` toggles, and `@[mention]` — is auto-translated before posting. Note: local images are appended at the end of the page rather than inline with this engine; use `--engine blocks` when image position matters. Pass `--allow-deleting-content` when `--replace` needs to remove child pages or databases. + +```bash +# Markdown engine — create a DB row from a doc with callouts or columns +python notion_writer.py -d DB_URL -t "Notes" --engine markdown -f notes.md +``` + ## Workflow Example Integrate with Jamie YouTube Manager to log video info: diff --git a/custom-skills/32-notion-writer/code/CLAUDE.md b/custom-skills/32-notion-writer/code/CLAUDE.md index 4ee757d..af5951d 100644 --- a/custom-skills/32-notion-writer/code/CLAUDE.md +++ b/custom-skills/32-notion-writer/code/CLAUDE.md @@ -189,6 +189,53 @@ print("Hello") Notion's URL validator requires absolute URLs for link annotations. The parser converts TOC-style anchor links to bold to preserve navigation intent and silently strips relative paths. +### File uploads + +Standalone local-image lines (`![alt](./image.png)`) are auto-uploaded to Notion and embedded as `file_upload` image blocks. Remote images (`![](https://...)`) are left as external links unchanged. + +**Requirements:** +- `ntn` CLI installed: `curl -fsSL https://ntn.dev | bash` +- Logged in: `ntn login` + +Uploads are workspace-scoped — the file lands in whichever workspace the `ntn` CLI is authenticated to. Ensure this matches the workspace the Notion API token targets, or the image block will not attach. + +### Engines + +Two write engines, selected with `--engine {blocks,markdown}`. Default is `blocks`. + +| Engine | Flag | When to use | +|--------|------|-------------| +| **blocks** (default) | `--engine blocks` | General use; images embed at their exact position; full table + container support | +| **markdown** | `--engine markdown` | Richer Notion-native formatting via enhanced-markdown endpoints | + +**blocks engine** converts markdown to Notion block objects locally (via `markdown_to_notion_blocks`). Local images are uploaded via `ntn` and embedded at their exact position in the document. + +**markdown engine** posts the document through Notion's native enhanced-markdown endpoints (`Notion-Version: 2026-03-11`, set automatically). The skill's authoring dialect is auto-translated before posting: + +| Skill dialect | Translated to | +|---------------|---------------| +| `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` | `` | +| `::: columns` / `::: column` / `:::` | `...` | +| `
...` | `
` (Notion toggle) | +| `@[Title](id-or-url)` | `` | + +**Local image limitation with `--engine markdown`**: local images cannot be placed inline via the enhanced-markdown API. They are appended at the end of the page as a second write pass. Use `--engine blocks` when image placement matters. + +**`--notion-version`**: Override the API version for the markdown engine (default: `2026-03-11`). + +**`--allow-deleting-content`**: Required when `--replace` needs to delete child pages or databases under the target page; the Notion API refuses such deletions unless this flag is present. + +```bash +# Markdown engine, create a row from a doc with callouts/columns +python notion_writer.py -d DB_URL -t "Notes" --engine markdown -f notes.md + +# Blocks engine with a local image (auto-uploaded via ntn) +python notion_writer.py -p PAGE_URL -f post.md # post.md contains ![chart](./chart.png) + +# Markdown engine, replace page allowing child deletion +python notion_writer.py -p PAGE_URL -f doc.md --replace --engine markdown --allow-deleting-content +``` + --- ## Examples @@ -398,9 +445,10 @@ python notion_writer.py -d DB_URL -t "Title" --upsert-by "Name" -f content.md --- -*Version 1.2.0 | Claude Code | 2026-04-27* +*Version 1.3.0 | Claude Code | 2026-06-27* Changelog: +- 1.3.0 — Local file/image uploads via the `ntn` CLI (`![](local)` → file_upload image blocks). New `--engine markdown` path writing through Notion's native enhanced-markdown endpoints with a dialect translator. Added `--notion-version` and `--allow-deleting-content`. - 1.2.0 — Extended block coverage: GitHub-alert callouts, HTML5 `
` toggles, Pandoc `::: columns` fenced div, inline `@[Title](id-or-url)` page mentions. Parser made reentrant to support full recursion inside container blocks. - 1.1.0 — Migrated to Notion API 2025-09-03 (multi-source databases). Added `--properties` JSON flag, `--upsert-by` for idempotency, anchor-link parser fix, friendlier API error messages. - 1.0.0 — Initial release with markdown→Notion block conversion.