From 6446f0052223b9f5fa05db8bbd7e239f2599530b Mon Sep 17 00:00:00 2001
From: Andrew Yim <andrew.yim@dintelligence.co.kr>
Date: Mon, 27 Apr 2026 11:38:53 +0900
Subject: [PATCH] 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>
---
 custom-skills/32-notion-writer/code/CLAUDE.md | 67 ++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/custom-skills/32-notion-writer/code/CLAUDE.md b/custom-skills/32-notion-writer/code/CLAUDE.md
index d1dc514..4ee757d 100644
--- a/custom-skills/32-notion-writer/code/CLAUDE.md
+++ b/custom-skills/32-notion-writer/code/CLAUDE.md
@@ -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.