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:
2026-04-27 11:38:53 +09:00
parent 707405b940
commit 6446f00522

View File

@@ -157,8 +157,12 @@ When upserting, `--file` (or `--stdin`) replaces the page's body blocks; `--prop
| `- [ ] task` | To-do (unchecked) |
| `- [x] task` | To-do (checked) |
| `> 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 |
| `---` | Divider |
| Tables (`\| col \|`) | Table |
| Paragraphs | Paragraph |
### Code Block Languages
@@ -181,6 +185,7 @@ print("Hello")
| `[text](https://...)` | link (absolute URLs only) |
| `[text](#anchor)` | bold (Notion rejects fragment 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.
@@ -205,6 +210,65 @@ python notion_writer.py \
--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
```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:
- 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.0.0 — Initial release with markdown→Notion block conversion.