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) |
|
||||
| `- [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.
|
||||
|
||||
Reference in New Issue
Block a user