@yeongjaeyou/claude-code-config 0.4.0 → 0.5.1

package/.claude/skills/notion-md-uploader/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: notion-md-uploader
+description: Upload Markdown files to Notion pages with full formatting support including headings, lists, code blocks, images, tables, callouts, and todos. This skill should be used when users want to publish documentation, reports, or notes from Markdown files to their Notion workspace with preserved formatting and automatic image uploads.
+---
+
+# Notion Markdown Uploader
+
+## Overview
+
+To upload Markdown files to Notion with full formatting preservation, use this skill. It converts Markdown syntax to Notion blocks and handles local image uploads automatically via the Notion File Upload API.
+
+## Prerequisites
+
+Before using this skill, ensure the following setup is complete:
+
+### 1. Notion Integration Setup
+
+1. Visit https://www.notion.so/my-integrations
+2. Click "+ New integration"
+3. Configure the integration:
+   - Name: "MD Uploader" (or preferred name)
+   - Associated workspace: Select target workspace
+   - Capabilities: Enable Read, Update, and Insert content
+4. Click "Submit" and copy the API key
+
+### 2. Environment Configuration
+
+Set the API key in the environment:
+
+```bash
+# In .env file
+NOTION_API_KEY=ntn_xxxxx
+
+# Or export directly
+export NOTION_API_KEY=ntn_xxxxx
+```
+
+### 3. Page Access
+
+Share the target parent page with the integration:
+
+1. Open the Notion page where documents will be uploaded
+2. Click "..." menu (top right)
+3. Select "Add connections"
+4. Find and select the integration
+
+## Quick Start
+
+### Basic Upload
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    docs/report.md \
+    --parent-page-id "abc123def456"
+```
+
+### With Custom Title
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    README.md \
+    --parent-page-id "abc123def456" \
+    --title "Project Documentation"
+```
+
+### Dry Run (Preview)
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    docs/analysis.md \
+    --parent-page-id "abc123def456" \
+    --dry-run
+```
+
+## Supported Markdown Elements
+
+| Element | Markdown Syntax | Notion Block |
+|---------|----------------|--------------|
+| Heading 1 | `# Title` | heading_1 |
+| Heading 2 | `## Subtitle` | heading_2 |
+| Heading 3 | `### Section` | heading_3 |
+| Paragraph | Plain text | paragraph |
+| Bold | `**text**` | bold annotation |
+| Italic | `*text*` | italic annotation |
+| Strikethrough | `~~text~~` | strikethrough annotation |
+| Inline Code | `` `code` `` | code annotation |
+| Link | `[text](url)` | link |
+| Bulleted List | `- item` | bulleted_list_item |
+| Numbered List | `1. item` | numbered_list_item |
+| Code Block | ` ```lang ``` ` | code (with language) |
+| Quote | `> text` | quote |
+| Divider | `---` | divider |
+| Image | `![alt](path)` | image (with upload) |
+| Table | `\| A \| B \|` | table + table_row |
+| Todo | `- [ ] task` | to_do |
+| Callout | `> [!NOTE]` | callout |
+
+## Image Handling
+
+### External URLs
+
+Images with HTTP/HTTPS URLs are embedded directly:
+
+```markdown
+![Logo](https://example.com/logo.png)
+```
+
+### Local Images
+
+Local images are automatically uploaded to Notion:
+
+```markdown
+![Chart](./figures/chart.png)
+![Result](../outputs/result.jpg)
+```
+
+The uploader:
+1. Detects local image paths
+2. Creates a Notion File Upload object
+3. Uploads the image binary
+4. Attaches the uploaded file to an image block
+
+Supported formats: `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`
+
+## Finding Parent Page ID
+
+### Option 1: From URL
+
+Copy the page URL and extract the ID:
+
+```
+https://www.notion.so/workspace/Page-Title-abc123def456ghi789
+                                        ^^^^^^^^^^^^^^^^^^^^^^^^
+                                        This is the page ID (32 chars)
+```
+
+### Option 2: Use Search API
+
+```bash
+# The script accepts full URLs
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    report.md \
+    --parent-page-id "https://www.notion.so/workspace/Reports-abc123"
+```
+
+## Workflow Decision Tree
+
+```
+User wants to upload Markdown to Notion
+    |
+    +-- Is NOTION_API_KEY set?
+    |   +-- No: Set up integration (see Prerequisites)
+    |   +-- Yes: Continue
+    |
+    +-- Is parent page shared with integration?
+    |   +-- No: Add connection to page
+    |   +-- Yes: Continue
+    |
+    +-- Run upload script
+        +-- Has local images?
+        |   +-- Yes: Images uploaded automatically
+        |   +-- No: Continue
+        |
+        +-- Success: Page created with URL
+```
+
+## Scripts
+
+### upload_md.py
+
+Main upload script. Run with `--help` for full options:
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py --help
+```
+
+Arguments:
+- `md_file`: Path to Markdown file (required)
+- `--parent-page-id`, `-p`: Notion parent page ID or URL (required)
+- `--title`, `-t`: Custom page title (optional)
+- `--dry-run`: Preview without uploading (optional)
+
+### notion_client.py
+
+Low-level Notion API client. Can be imported for custom workflows:
+
+```python
+from scripts.notion_client import NotionClient
+
+client = NotionClient()
+page = client.create_page(
+    parent_page_id="abc123",
+    title="My Page",
+    children=[...]
+)
+```
+
+### markdown_parser.py
+
+Markdown parser for converting to AST. Useful for custom processing:
+
+```python
+from scripts.markdown_parser import MarkdownParser
+
+parser = MarkdownParser()
+blocks = parser.parse(markdown_text)
+```
+
+### notion_converter.py
+
+Converts parsed Markdown blocks to Notion API format:
+
+```python
+from scripts.notion_converter import NotionBlockConverter
+
+converter = NotionBlockConverter(image_uploader=upload_func)
+notion_blocks = converter.convert_blocks(blocks)
+```
+
+## Limitations
+
+1. **Block Limit**: Notion API allows max 100 blocks per request. The script handles this by chunking.
+2. **File Size**: Images must be under 20MB (5MB for free workspaces)
+3. **Nested Lists**: Currently flattened (nested items become top-level)
+4. **Complex Tables**: Cell formatting may be simplified
+5. **Attachments**: Only images are auto-uploaded; other files need manual handling
+
+## Troubleshooting
+
+### "Could not find page" Error
+
+The parent page is not shared with the integration:
+1. Open the page in Notion
+2. Click "..." > "Add connections"
+3. Select your integration
+
+### "unauthorized" Error
+
+API key is invalid or not set:
+1. Check `NOTION_API_KEY` in `.env`
+2. Verify the key at https://www.notion.so/my-integrations
+
+### Image Upload Failed
+
+1. Check file exists at the specified path
+2. Verify file size is under limit
+3. Ensure file format is supported
+
+## References
+
+- `references/notion_block_types.md` - Detailed Notion block type reference
+- `references/setup_guide.md` - Step-by-step integration setup guide

package/.claude/skills/notion-md-uploader/references/notion_block_types.md

@@ -0,0 +1,323 @@
+# Notion Block Types Reference
+
+This document provides a comprehensive reference for Notion API block types used by the uploader.
+
+## Block Object Structure
+
+Every Notion block follows this base structure:
+
+```json
+{
+  "object": "block",
+  "id": "block-uuid",
+  "type": "block_type",
+  "created_time": "2024-01-01T00:00:00.000Z",
+  "last_edited_time": "2024-01-01T00:00:00.000Z",
+  "has_children": false,
+  "{block_type}": {
+    // type-specific properties
+  }
+}
+```
+
+## Text Block Types
+
+### Paragraph
+
+```json
+{
+  "type": "paragraph",
+  "paragraph": {
+    "rich_text": [
+      {
+        "type": "text",
+        "text": { "content": "Paragraph text" },
+        "annotations": {
+          "bold": false,
+          "italic": false,
+          "strikethrough": false,
+          "underline": false,
+          "code": false,
+          "color": "default"
+        }
+      }
+    ],
+    "color": "default"
+  }
+}
+```
+
+### Headings
+
+```json
+// heading_1, heading_2, heading_3
+{
+  "type": "heading_1",
+  "heading_1": {
+    "rich_text": [{"type": "text", "text": {"content": "Heading"}}],
+    "color": "default",
+    "is_toggleable": false
+  }
+}
+```
+
+### Quote
+
+```json
+{
+  "type": "quote",
+  "quote": {
+    "rich_text": [{"type": "text", "text": {"content": "Quote text"}}],
+    "color": "default"
+  }
+}
+```
+
+### Callout
+
+```json
+{
+  "type": "callout",
+  "callout": {
+    "rich_text": [{"type": "text", "text": {"content": "Note content"}}],
+    "icon": {"type": "emoji", "emoji": "i"},
+    "color": "default"
+  }
+}
+```
+
+## List Block Types
+
+### Bulleted List Item
+
+```json
+{
+  "type": "bulleted_list_item",
+  "bulleted_list_item": {
+    "rich_text": [{"type": "text", "text": {"content": "Item"}}],
+    "color": "default",
+    "children": []  // optional nested blocks
+  }
+}
+```
+
+### Numbered List Item
+
+```json
+{
+  "type": "numbered_list_item",
+  "numbered_list_item": {
+    "rich_text": [{"type": "text", "text": {"content": "Item"}}],
+    "color": "default",
+    "children": []
+  }
+}
+```
+
+### To-Do
+
+```json
+{
+  "type": "to_do",
+  "to_do": {
+    "rich_text": [{"type": "text", "text": {"content": "Task"}}],
+    "checked": false,
+    "color": "default"
+  }
+}
+```
+
+## Code Block
+
+```json
+{
+  "type": "code",
+  "code": {
+    "rich_text": [{"type": "text", "text": {"content": "print('hello')"}}],
+    "language": "python",
+    "caption": []
+  }
+}
+```
+
+### Supported Languages
+
+```
+abap, arduino, bash, basic, c, clojure, coffeescript, c++, c#, css,
+dart, diff, docker, elixir, elm, erlang, flow, fortran, f#, gherkin,
+glsl, go, graphql, groovy, haskell, html, java, javascript, json,
+julia, kotlin, latex, less, lisp, livescript, lua, makefile, markdown,
+markup, matlab, mermaid, nix, objective-c, ocaml, pascal, perl, php,
+plain text, powershell, prolog, protobuf, python, r, reason, ruby,
+rust, sass, scala, scheme, scss, shell, sql, swift, typescript,
+vb.net, verilog, vhdl, visual basic, webassembly, xml, yaml
+```
+
+## Media Block Types
+
+### Image
+
+External URL:
+```json
+{
+  "type": "image",
+  "image": {
+    "type": "external",
+    "external": {"url": "https://example.com/image.png"},
+    "caption": []
+  }
+}
+```
+
+File Upload:
+```json
+{
+  "type": "image",
+  "image": {
+    "type": "file_upload",
+    "file_upload": {"id": "file-upload-uuid"},
+    "caption": []
+  }
+}
+```
+
+### File
+
+```json
+{
+  "type": "file",
+  "file": {
+    "type": "file_upload",
+    "file_upload": {"id": "file-upload-uuid"},
+    "name": "document.pdf"
+  }
+}
+```
+
+## Table Block Types
+
+### Table
+
+```json
+{
+  "type": "table",
+  "table": {
+    "table_width": 3,
+    "has_column_header": true,
+    "has_row_header": false,
+    "children": [/* table_row blocks */]
+  }
+}
+```
+
+### Table Row
+
+```json
+{
+  "type": "table_row",
+  "table_row": {
+    "cells": [
+      [{"type": "text", "text": {"content": "Cell 1"}}],
+      [{"type": "text", "text": {"content": "Cell 2"}}],
+      [{"type": "text", "text": {"content": "Cell 3"}}]
+    ]
+  }
+}
+```
+
+## Other Block Types
+
+### Divider
+
+```json
+{
+  "type": "divider",
+  "divider": {}
+}
+```
+
+### Bookmark
+
+```json
+{
+  "type": "bookmark",
+  "bookmark": {
+    "url": "https://example.com",
+    "caption": []
+  }
+}
+```
+
+## Rich Text Object
+
+Rich text objects are used within blocks for formatted text:
+
+```json
+{
+  "type": "text",
+  "text": {
+    "content": "Text content",
+    "link": {"url": "https://example.com"}  // optional
+  },
+  "annotations": {
+    "bold": false,
+    "italic": false,
+    "strikethrough": false,
+    "underline": false,
+    "code": false,
+    "color": "default"
+  },
+  "plain_text": "Text content",
+  "href": null
+}
+```
+
+### Available Colors
+
+```
+default, gray, brown, orange, yellow, green, blue, purple, pink, red
+gray_background, brown_background, orange_background, yellow_background,
+green_background, blue_background, purple_background, pink_background, red_background
+```
+
+## File Upload Object
+
+Used for uploading local files to Notion:
+
+```json
+{
+  "object": "file_upload",
+  "id": "uuid",
+  "status": "uploaded",
+  "filename": "image.png",
+  "content_type": "image/png",
+  "content_length": 12345
+}
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/pages` | POST | Create a new page |
+| `/v1/blocks/{id}/children` | PATCH | Append blocks to page |
+| `/v1/blocks/{id}/children` | GET | Retrieve child blocks |
+| `/v1/file_uploads` | POST | Create file upload |
+| `/v1/file_uploads/{id}/send` | POST | Upload file content |
+
+## Rate Limits
+
+- Average: 3 requests per second
+- Burst: Up to 3 concurrent requests
+- Block limit: 100 blocks per request
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request body |
+| 401 | Invalid API key |
+| 403 | Access denied to resource |
+| 404 | Resource not found |
+| 429 | Rate limit exceeded |
+| 500 | Internal server error |

package/.claude/skills/notion-md-uploader/references/setup_guide.md

@@ -0,0 +1,156 @@
+# Notion Integration Setup Guide
+
+This guide walks through setting up a Notion integration for the Markdown uploader.
+
+## Step 1: Create a Notion Integration
+
+1. Go to https://www.notion.so/my-integrations
+2. Click "+ New integration"
+3. Fill in the form:
+   - **Name**: Choose a descriptive name (e.g., "MD Uploader")
+   - **Logo**: Optional
+   - **Associated workspace**: Select your target workspace
+4. Click "Submit"
+
+## Step 2: Configure Capabilities
+
+After creation, configure the integration's capabilities:
+
+### Content Capabilities
+
+Enable all of these for full functionality:
+
+- **Read content**: Required for verifying pages
+- **Update content**: Required for appending blocks
+- **Insert content**: Required for creating pages and uploading files
+
+### User Capabilities
+
+- **Read user information including email addresses**: Not required
+- **No user information**: Sufficient for this tool
+
+### Comment Capabilities
+
+- Not required for the uploader
+
+## Step 3: Copy the API Key
+
+1. On the integration page, find the "Internal Integration Secret"
+2. Click "Show" then "Copy"
+3. Store this securely - it cannot be retrieved again
+
+## Step 4: Set Environment Variable
+
+### Option A: .env File (Recommended)
+
+Create or edit `.env` in your project root:
+
+```bash
+NOTION_API_KEY=ntn_xxxxxxxxxxxxxxxxxxxxx
+```
+
+### Option B: Export in Shell
+
+```bash
+export NOTION_API_KEY=ntn_xxxxxxxxxxxxxxxxxxxxx
+```
+
+### Option C: Session-specific
+
+```bash
+NOTION_API_KEY=ntn_xxx uv run python upload_md.py ...
+```
+
+## Step 5: Share Pages with Integration
+
+The integration can only access pages explicitly shared with it.
+
+### Sharing a Single Page
+
+1. Open the target page in Notion
+2. Click the "..." menu (top right corner)
+3. Select "Add connections"
+4. Search for your integration name
+5. Click to add
+
+### Sharing a Database
+
+Same process as above, but on the database page.
+
+### Sharing Child Pages
+
+When you share a parent page, all child pages are also accessible.
+
+## Step 6: Find Page ID
+
+### From Browser URL
+
+1. Open the page in Notion
+2. Copy the URL: `https://www.notion.so/Page-Title-abc123def456ghi789jkl012`
+3. The ID is the 32-character string at the end: `abc123def456ghi789jkl012`
+
+### From Share Link
+
+1. Click "Share" > "Copy link"
+2. Extract the ID from the URL
+
+### Format Requirements
+
+The script accepts:
+- Raw 32-character ID: `abc123def456ghi789jkl012`
+- UUID format: `abc123de-f456-ghi7-89jk-l012mnopqrst`
+- Full URL: `https://www.notion.so/...`
+
+## Verification
+
+Test the setup:
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    --help
+```
+
+Then try a dry run:
+
+```bash
+uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
+    README.md \
+    --parent-page-id YOUR_PAGE_ID \
+    --dry-run
+```
+
+## Troubleshooting
+
+### "unauthorized" Error
+
+1. Verify the API key is correct
+2. Check there are no extra spaces or newlines
+3. Regenerate the key if needed
+
+### "Could not find page" Error
+
+1. Confirm the page ID is correct
+2. Ensure the page is shared with the integration
+3. Check the integration has the required capabilities
+
+### "validation_error" for File Upload
+
+1. File may exceed size limit (20MB, or 5MB for free plans)
+2. File type may not be supported
+3. Check the file exists at the specified path
+
+## Security Best Practices
+
+1. **Never commit API keys**: Add `.env` to `.gitignore`
+2. **Use environment variables**: Don't hardcode keys
+3. **Limit access**: Only share necessary pages
+4. **Rotate keys**: Regenerate periodically
+5. **Monitor usage**: Check integration logs in Notion
+
+## Workspace Limits
+
+| Feature | Free | Plus/Business |
+|---------|------|---------------|
+| Max file size | 5 MB | 5 GB |
+| API rate limit | 3 req/s | 3 req/s |
+| Blocks per request | 100 | 100 |