docs(notion-writer): document Phase 3c block coverage + bump to v1.2.0
Adds rows for callouts, toggles, columns, and page mentions in the supported-elements and inline rich-text tables. Adds usage examples for each. Updates version footer with changelog entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -157,8 +157,12 @@ When upserting, `--file` (or `--stdin`) replaces the page's body blocks; `--prop
|
|||||||
| `- [ ] task` | To-do (unchecked) |
|
| `- [ ] task` | To-do (unchecked) |
|
||||||
| `- [x] task` | To-do (checked) |
|
| `- [x] task` | To-do (checked) |
|
||||||
| `> quote` | Quote |
|
| `> quote` | Quote |
|
||||||
|
| `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` | Callout (with icon + colored background) |
|
||||||
|
| `<details><summary>X</summary> ... </details>` | Toggle (multi-line form, recursive children) |
|
||||||
|
| `::: columns / ::: column / :::` | Column list (Pandoc fenced div, ≥2 columns required) |
|
||||||
| `` ```code``` `` | Code block |
|
| `` ```code``` `` | Code block |
|
||||||
| `---` | Divider |
|
| `---` | Divider |
|
||||||
|
| Tables (`\| col \|`) | Table |
|
||||||
| Paragraphs | Paragraph |
|
| Paragraphs | Paragraph |
|
||||||
|
|
||||||
### Code Block Languages
|
### Code Block Languages
|
||||||
@@ -181,6 +185,7 @@ print("Hello")
|
|||||||
| `[text](https://...)` | link (absolute URLs only) |
|
| `[text](https://...)` | link (absolute URLs only) |
|
||||||
| `[text](#anchor)` | bold (Notion rejects fragment URLs) |
|
| `[text](#anchor)` | bold (Notion rejects fragment URLs) |
|
||||||
| `[text](relative/path.md)` | plain text (Notion rejects relative URLs) |
|
| `[text](relative/path.md)` | plain text (Notion rejects relative URLs) |
|
||||||
|
| `@[Title](page-id-or-notion-url)` | page mention (resolves via Notion URL or raw 32-hex ID) |
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
@@ -205,6 +210,65 @@ python notion_writer.py \
|
|||||||
--file meeting_notes.md
|
--file meeting_notes.md
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Callouts (GitHub alerts)
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
> [!NOTE]
|
||||||
|
> Just FYI: this method is idempotent.
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> Don't run this in production without a backup.
|
||||||
|
````
|
||||||
|
|
||||||
|
Renders as Notion callout blocks with corresponding emoji icon and colored background.
|
||||||
|
|
||||||
|
### Toggles (HTML5 `<details>`)
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
<details>
|
||||||
|
<summary>Click to expand: full debug log</summary>
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ python notion_writer.py --test
|
||||||
|
✅ Connected
|
||||||
|
```
|
||||||
|
|
||||||
|
Lists, code blocks, and even nested `<details>` work inside.
|
||||||
|
</details>
|
||||||
|
````
|
||||||
|
|
||||||
|
Multi-line form required: `<details>` and `</details>` must be on their own lines.
|
||||||
|
|
||||||
|
### Columns (Pandoc fenced div)
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
::: columns
|
||||||
|
::: column
|
||||||
|
**Column 1**
|
||||||
|
|
||||||
|
- item a
|
||||||
|
- item b
|
||||||
|
:::
|
||||||
|
::: column
|
||||||
|
**Column 2**
|
||||||
|
|
||||||
|
```python
|
||||||
|
print("hello")
|
||||||
|
```
|
||||||
|
:::
|
||||||
|
:::
|
||||||
|
````
|
||||||
|
|
||||||
|
≥2 columns required by Notion. Single-column blocks degrade to plain paragraphs.
|
||||||
|
|
||||||
|
### Page mentions
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
See @[Architecture Decision Record](https://notion.so/ADR-abcdef0123456789abcdef0123456789) for context.
|
||||||
|
```
|
||||||
|
|
||||||
|
Both Notion URLs and raw 32-hex IDs work. Invalid targets fall back to plain text `@Title`.
|
||||||
|
|
||||||
### Pipe from Another Tool
|
### Pipe from Another Tool
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -334,8 +398,9 @@ python notion_writer.py -d DB_URL -t "Title" --upsert-by "Name" -f content.md
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Version 1.1.0 | Claude Code | 2026-04-27*
|
*Version 1.2.0 | Claude Code | 2026-04-27*
|
||||||
|
|
||||||
Changelog:
|
Changelog:
|
||||||
|
- 1.2.0 — Extended block coverage: GitHub-alert callouts, HTML5 `<details>` 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.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.
|
- 1.0.0 — Initial release with markdown→Notion block conversion.
|
||||||
|
|||||||
Reference in New Issue
Block a user