# Notion Sync Optimization Guide

**Last Updated:** 2026-03-13

## Problem Statement

Previous Notion sync process was inefficient:
- Content was prepared but not actually synced
- Large files (32KB+) require special handling
- No automated validation before sync
- Manual steps prone to errors

## Optimized Sync Process

### 1. Preparation Phase (Automated)

**Script:** `v2/scripts/notion/sync-resource-creation-plan.py`

**Steps:**
1. Read markdown file
2. Remove H1 title (if present)
3. Validate formatting (tables, H2 toggles)
4. Save prepared content to `/tmp/resource-creation-plan-notion.md`

**Validation Checks:**
- Table separators use `|---|` format (no alignment colons)
- H2 toggles have properly indented content
- No internal file paths in content

### 2. Sync Phase (MCP Tool)

**Tool:** `notion-update-page` via `call_mcp_tool`

**Parameters:**
```json
{
  "page_id": "3227d540832a81af8110c49196885d8b",
  "command": "replace_content",
  "new_str": "<full_content_from_prepared_file>"
}
```

**For Large Files (>30KB):**
- Read content in chunks if needed
- Use `replace_content` command (replaces entire page)
- Verify sync success by checking page_id return

### 3. Verification Phase

**Post-Sync Checks:**
1. Verify page_id returned successfully
2. Check Notion page renders correctly
3. Validate tables display properly
4. Confirm H2 toggles expand/collapse correctly

## Quick Sync Command

For Resource Creation Plan specifically:

```bash
python3 v2/scripts/notion/sync-resource-creation-plan.py
# Then use MCP tool with prepared content
```

## Performance Optimizations

1. **Batch Validation**: Run all formatting checks in single pass
2. **Cached Preparation**: Save prepared content to avoid re-processing
3. **Direct MCP Calls**: Use `call_mcp_tool` directly, not intermediate scripts
4. **Error Handling**: Validate content before sync attempt

## Common Issues & Solutions

### Issue: Content too large for single API call
**Solution**: Notion API handles up to ~50KB. For larger files, consider:
- Splitting into multiple pages
- Using `update_content` with multiple `content_updates` instead of `replace_content`

### Issue: Tables render incorrectly
**Solution**: Ensure separators use `|---|` format, not `|:---|` or `|:---:|`

### Issue: H2 toggles don't nest content
**Solution**: Indent all content under toggle with tab or 2+ spaces

### Issue: Sync appears successful but content not updated
**Solution**: 
- Check page_id is correct
- Verify content was actually sent (check character count)
- Refresh Notion page (may need hard refresh)

## Future Improvements

1. **Automated Sync Script**: Create Python script that calls MCP tool directly
2. **Diff Detection**: Only sync changed sections
3. **Multi-Page Support**: Handle syncing to multiple Notion pages
4. **Sync Logging**: Track sync history and failures