# Notion Writer - Claude Code Skill

> **Purpose**: Push markdown content to Notion pages or databases
> **Platform**: Claude Code (CLI)
> **Input**: Markdown files, Notion URLs
> **Output**: Content written to Notion

---

## Capabilities

| Feature | Input | Output |
|---------|-------|--------|
| Page Content Append | Markdown + Page URL | Appended blocks |
| Page Content Replace | Markdown + Page URL | Replaced content |
| Database Row Create | Markdown + DB URL + Title | New database row |
| Connection Test | API token | Connection status |
| Page/DB Info | URL | Metadata |

---

## Setup

### 1. Create Notion Integration

1. Go to [Notion Integrations](https://www.notion.so/my-integrations)
2. Click "New integration"
3. Name it (e.g., "Claude Writer")
4. Select workspace
5. Copy the "Internal Integration Token"

### 2. Share Pages/Databases with Integration

**Important**: You must share each page or database with your integration:
1. Open the Notion page/database
2. Click "..." menu → "Connections"
3. Add your integration

### 3. Configure Environment

```bash
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts

# Create .env from example
cp .env.example .env

# Edit and add your token
nano .env
```

`.env` file:
```
NOTION_API_KEY=secret_your_integration_token
```

### 4. Activate Environment

```bash
source venv/bin/activate
```

---

## Usage

### Test Connection

```bash
python notion_writer.py --test
```

### Get Page/Database Info

```bash
# Page info
python notion_writer.py --page "https://notion.so/My-Page-abc123" --info

# Database info
python notion_writer.py --database "https://notion.so/abc123" --info
```

### Write to Page

```bash
# Append content to page
python notion_writer.py --page PAGE_URL --file content.md

# Replace page content
python notion_writer.py --page PAGE_URL --file content.md --replace

# From stdin
cat report.md | python notion_writer.py --page PAGE_URL --stdin
```

### Create Database Row

```bash
# Create row with title and content
python notion_writer.py --database DB_URL --title "New Entry" --file content.md

# Title only
python notion_writer.py --database DB_URL --title "Empty Entry"
```

---

## Markdown Support

### Supported Elements

| Markdown | Notion Block |
|----------|--------------|
| `# Heading` | Heading 1 |
| `## Heading` | Heading 2 |
| `### Heading` | Heading 3 |
| `- item` | Bulleted list |
| `1. item` | Numbered list |
| `- [ ] task` | To-do (unchecked) |
| `- [x] task` | To-do (checked) |
| `> quote` | Quote |
| `` ```code``` `` | Code block |
| `---` | Divider |
| Paragraphs | Paragraph |

### Code Block Languages

Specify language after opening backticks:
```markdown
```python
print("Hello")
```
```

---

## Examples

### Push SEO Audit Report

```bash
python notion_writer.py \
  --page "https://notion.so/SEO-Reports-abc123" \
  --file ~/reports/seo_audit_2025.md
```

### Create Meeting Notes Entry

```bash
python notion_writer.py \
  --database "https://notion.so/Meeting-Notes-abc123" \
  --title "Weekly Standup - Dec 26" \
  --file meeting_notes.md
```

### Pipe from Another Tool

```bash
# Pipe YouTube video info to Notion
python jamie_video_info.py VIDEO_ID --json | \
  python notion_writer.py --page PAGE_URL --stdin
```

---

## API Limits

| Limit | Value |
|-------|-------|
| Blocks per request | 100 |
| Text content per block | 2,000 chars |
| Requests per second | ~3 |

The script automatically batches large content.

---

## Troubleshooting

### "Could not find page"
- Ensure page is shared with your integration
- Check URL/ID is correct

### "Invalid token"
- Verify NOTION_API_KEY in .env
- Token should start with `secret_`

### "Rate limited"
- Wait and retry
- Script handles batching but rapid calls may hit limits

---

## File Structure

```
02-notion-writer/
├── code/
│   ├── CLAUDE.md              # This skill document
│   ├── scripts/
│   │   ├── notion_writer.py   # Main script
│   │   ├── venv/              # Python environment
│   │   ├── .env               # API token (not committed)
│   │   └── .env.example       # Template
│   ├── output/                # For generated content
│   └── references/
└── desktop/                   # Claude Desktop version (future)
```

---

## Quick Reference

```bash
# Navigate
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts
source venv/bin/activate

# Test
python notion_writer.py --test

# Write to page
python notion_writer.py -p PAGE_URL -f content.md

# Replace content
python notion_writer.py -p PAGE_URL -f content.md -r

# Create DB row
python notion_writer.py -d DB_URL -t "Title" -f content.md
```

---

*Version 1.0.0 | Claude Code | 2025-12-26*