notion-content-pipeline

push local .md files to notion and pull edits back. track a content pipeline db with statuses (seed → draft → review → published).

---

intent

sync markdown files bidirectionally with notion for content editing workflows. use this when: pushing local drafts to notion for review/editing, pulling notion edits back to local files, advancing posts through a content pipeline (draft → humanized → in review → approved), or managing pipeline database records with statuses and metadata. the skill handles markdown to notion block conversion, maintains a local file-to-page-id sync map, and provides batch and per-file operations. do not use this for one-off notion queries, arbitrary database reads, or social media publishing (use buffer-publisher instead).

---

inputs

environment variables:

• NOTION_API_KEY (required): notion integration token. fetch from 1password: op read "op://OpenClaw/bg2gpqhpta6an5n4prn2zzycya/credential". do not use the stale item op://OpenClaw/Notion API Key/credential (deleted as of early 2026).
• NOTION_PARENT_PAGE_ID (required for create operations): parent page id where new pipeline db and content pages are created. must be a notion uuid.
• NOTION_PIPELINE_DB_ID (optional): content pipeline database id. defaults to 322eb552-581a-8111-8f6a-d042dd048ec8. override if using a different pipeline db.
• NOTION_SYNC_MAP (optional): path to sync map json file. defaults to ./notion_sync_map.json.
• CONTENT_DIR (optional): directory containing markdown files. defaults to ./content.

external connection:

• notion api v2022-06-28. requires outbound https. integration token must have:
  • read/write access to parent page and all child pages
  • database query and page creation permissions
  • no rate limit issues for batch operations under 100 pages (notion api: 3 requests/second soft limit)

local files:

• markdown files in content directory (.md extension expected)
• sync map json file (created and maintained automatically)
• python3 runtime with requests library

internal dependencies:

• skills/fact-checker/scripts/fact_check.py (optional, for pipeline_advance.py; skips gracefully if missing)

database ids (hardcoded reference):

• content pipeline db: 322eb552-581a-8111-8f6a-d042dd048ec8 (blog posts, n8n triggers)
• tweet pipeline db: 314c9a82-0734-81be-ac58-ddd878576cf0 (cron triggers)

---

procedure

step 1: validate credentials and environment

input: NOTION_API_KEY env var, NOTION_PARENT_PAGE_ID env var (or cli flag --sandbox-id)

output: api key confirmed valid via test request to notion api; parent page id confirmed accessible

1. read NOTION_API_KEY from environment or 1password
2. extract notion integration token (remove "secret_" prefix if present)
3. send test request to notion api with header Notion-Version: 2022-06-28 and bearer auth
4. if 401: raise "api key invalid or expired. fetch from 1password item bg2gpqhpta6an5n4prn2zzycya"
5. if parent page id provided, fetch parent page metadata to confirm access (404 = integration not shared with page)
6. store api key and parent page id in memory for remaining steps

decision: if no api key found, halt with instructions to set env var or cli flag. if parent page not accessible, halt with instructions to share integration in notion ui (connections panel).

---

step 2: load or initialize sync map

input: NOTION_SYNC_MAP env var or ./notion_sync_map.json default

output: in-memory dict mapping local file paths to notion page ids, e.g. {"content/my-post.md": "abc123-..."}

1. check if sync map file exists at configured path
2. if exists: read json, parse into dict
3. if missing: initialize empty dict {}
4. store in memory for push/pull operations

edge case: if sync map is corrupted (invalid json), log warning and initialize empty dict (forces full re-sync on next push)

---

step 3: push single file to notion

input: local file path (e.g. content/my-post.md), optional --no-overwrite flag, optional --slug for pipeline db property

output: notion page id, notion page url, sync map updated with file-to-id mapping

1. read markdown file from disk
2. parse markdown: extract title (first h1) and convert content to notion blocks
3. check sync map for existing page id:
   • if entry exists and --no-overwrite flag set: skip push, return existing page id
   • if entry exists and no flag: archive existing notion page (move to trash), proceed to create new page
4. create new notion page:
   • parent: NOTION_PARENT_PAGE_ID
   • title: extracted h1 from markdown
   • blocks: converted notion blocks from markdown body
   • if --slug provided: set Slug property to value (only for pipeline db pages)
5. capture notion page id and url from response
6. update sync map: {file_path: page_id}
7. write sync map back to disk
8. return page id, url, success indicator

edge cases:

• markdown file missing: raise "file not found"
• markdown parse error (malformed frontmatter, invalid unicode): log error, attempt best-effort conversion
• annotation parser error (nested bold/italic, leading emphasis): catch 400 from notion api, log "markdown annotation parse error" with line number hint
• notion api timeout (>30s): retry up to 2 times with 2s backoff
• notion api 429 (rate limit): wait 60s, retry once
• parent page 404: raise "parent page not found or integration not shared"

---

step 4: push all files (batch)

input: CONTENT_DIR directory path, optional --parallel flag

output: list of (file_path, page_id, status) tuples; sync map updated for all files

1. scan CONTENT_DIR for all .md files
2. for each file: call step 3 (push single file)
3. collect results: (path, page_id, status: success/failed)
4. if any push fails, log failure with error reason but continue (no early exit)
5. write final sync map after all files processed
6. return results list and summary: "pushed X/Y files, Z failures"

edge case: if CONTENT_DIR is empty or missing, return empty results list and warning

---

step 5: pull notion edits back to local file

input: local file path (e.g. content/my-post.md), optional --force-create flag

output: markdown file updated on disk with notion page content; sync map used to locate notion page

1. check sync map for file path:
   • if found: use stored page id
   • if not found and no --force-create flag: raise "file not tracked. push first or use --force-create"
2. fetch notion page content via api (page id, all blocks)
3. extract page title and properties (e.g., status, slug)
4. convert notion blocks back to markdown
5. preserve local markdown frontmatter (yaml header) if present; merge with notion data
6. write markdown file back to disk (overwrite local content with notion edits)
7. return file path, blocks count, success indicator

edge cases:

• notion page not found (404): remove entry from sync map, raise "page id in sync map points to deleted notion page"
• notion blocks include unsupported types (e.g., embed, synced block): log warning "block type not convertible to markdown, skipped" and continue
• notion api timeout: retry up to 2 times with 2s backoff
• markdown file locked by editor: raise "file currently open in editor, close and retry"

---

step 6: list tracked pages

input: sync map

output: table of (file_path, notion_page_id, notion_url) rows

1. load sync map from memory
2. for each entry: construct notion page url from page id (format: https://www.notion.so/{page_id_with_hyphens})
3. format and print table: file path | page id | url
4. return list of dicts for programmatic use

---

step 7: create content pipeline database

input: NOTION_PARENT_PAGE_ID, pipeline db schema specification

output: new notion database page id, sync map updated

1. check if pipeline db already exists (query parent page for child db with title "content pipeline")
   • if exists: return existing db id with warning "db already exists"
2. create new database page:
   • parent: NOTION_PARENT_PAGE_ID
   • title: "Content Pipeline"
   • schema properties:
     • title: database title (default)
     • slug (rich_text): url slug (lowercase hyphens, required by n8n for publishing)
     • platform (select): options [blog, linkedin, both]
     • status (select): options [seed, draft, humanized, in review, approved, in publishing, published]
     • hook (rich_text): one-sentence pitch
     • est. read time (select): options [<1 min, 2-3 min, 5-7 min, 10+ min]
     • published url (url): final url after publish (set by n8n)
     • pr url (url): github pr url (set by n8n)
     • source (rich_text): idea origin
3. capture database id from response
4. return db id and success indicator

critical: slug property must be present and populated. n8n reads props.slug?.rich_text and silently skips publishing if slug is empty, even when status = approved.

---

step 8: pipeline advance (round-trip workflow)

input: local file path, optional flags: --skip-humanize, --skip-factcheck, --dry-run

output: file updated on disk, notion page recreated, status advanced in pipeline db, diff and factcheck reports written

1. pull: call step 5 (pull notion edits back to local file)
2. humanize: apply mechanical text fixes:
   • replace em-dashes with commas or periods
   • replace "utilize" with "use", "impact" (verb) with "affect", "leverage" with "use", "synergy" with nothing
   • remove filler openers: "in order to", "at the end of the day", "to be honest"
   • reduce copula sentences ("is", "are", "be")
   • convert smart quotes to straight quotes
   • flag patterns for llm review: rule-of-three (three-item lists that may be mechanical), ai vocabulary (unprecedented, harness, unlock, reimagine used >1 per 500 words)
   • skip this step if --skip-humanize flag set
   • write diff report as {file_path}.humanizer.diff
3. fact-check: run skills/fact-checker/scripts/fact_check.py on humanized markdown:
   • skip gracefully if script missing
   • skip if --skip-factcheck flag set
   • write report as {file_path}.factcheck.txt
4. push: call step 3 (push file back to notion)
5. status advance in pipeline db:
   • query pipeline db for page matching file slug or title
   • current status draft: advance to humanized
   • current status humanized: advance to in review
   • never advance past in review (Nissan decides approval)
   • if --dry-run flag set: print proposed actions, do not write to disk or notion
6. return combined report: (file path, humanizer diff summary, factcheck summary, new notion page id, status change)

edge cases:

• file not in pipeline db yet: log warning "not found in pipeline db, push to db manually first"
• slug field missing from pipeline db: raise "pipeline db schema incomplete, run create_pipeline_db.py"
• fact-checker script missing: skip fact-check step gracefully, note in report
• humanizer encounters unsupported unicode: log warning, continue

---

step 9: handle overwrite behavior

input: push operation with existing sync map entry

output: old notion page archived, new page created

1. when pushing a file that's already tracked (entry in sync map):
   • fetch existing notion page id
   • send archive request (move page to trash/archive)
   • proceed to create fresh page (step 3)
   • this avoids block-count drift from repeated edits
2. to preserve existing page: use --no-overwrite flag in push command (skips if already tracked)

---

decision points

api key validation:

• if NOTION_API_KEY env var not set and no --api-key cli flag: halt with "set NOTION_API_KEY env var or provide --api-key flag"
• if api key test request returns 401: halt with "api key invalid or expired. fetch from 1password"

parent page access:

• if parent page returns 404: halt with "parent page id incorrect or integration not shared in notion ui (connections panel)"

sync map lookup (pull):

• if file path not in sync map and --force-create flag not set: raise "file not tracked. run push first or use --force-create"
• if file path in sync map and corresponding notion page is 404: remove sync map entry, raise "notion page was deleted. sync map cleaned"

overwrite on push:

• if file already in sync map and --no-overwrite flag set: skip push, return existing page id
• if file already in sync map and no flag: archive old page, create new page

pipeline advance status:

• if current status is draft and humanize + factcheck complete: advance to humanized
• if current status is humanized and factcheck complete: advance to in review
• if current status is in review or beyond: do not auto-advance (manual approval gate)
• if status field missing from page: raise "page not in pipeline db schema"

batch operations (push-all):

• if any file push fails: log error for that file but continue processing remaining files
• if all files fail: return summary with "all pushes failed" and exit code 1

dry-run mode:

• if --dry-run flag set: print all proposed actions, do not write to disk or notion, do not update sync map

notion api rate limiting:

• if 429 response: wait 60s, retry up to 1 time
• if 429 persists after retry: raise "notion api rate limit exceeded, try again in 1 minute"

notion api timeout:

• if request exceeds 30s: retry up to 2 times with 2s backoff between retries
• if timeout persists: raise "notion api timeout, check network connectivity"

slug field in pipeline db:

• if pushing to pipeline db and --slug not provided: raise "slug required for pipeline db pages. provide --slug or set in notion manually"
• if page already in pipeline db with empty slug: n8n will silently skip publishing (this is the known failure mode from 2026-03-28). warn user to set slug before advancing to approved status

markdown parse errors:

• if markdown title (h1) missing: use filename as title
• if markdown contains unsupported unicode or malformed frontmatter: log warning, attempt best-effort conversion and continue
• if annotation parser encounters nested bold/italic (**_text_**): catch notion 400 error, log hint about line number, offer to re-run with plain text fallback

---

output contract

push single file:

• success: returns json object with keys: page_id (uuid), page_url (notion.so url), status ("created" or "overwritten"), file_path (string), title (string)
• failure: raises error with reason (api key invalid, parent page not found, markdown parse error, etc.)
• side effect: sync map updated on disk; notion page created or archived+recreated

push all files (batch):

• success: returns list of result objects (one per file); each object contains file_path, page_id, status, page_url; summary line: "pushed X/Y files successfully"
• partial failure: returns list with mixed success/failure status per file; summary line: "pushed X/Y files, Z failures"; exit code 1 if any failures
• side effect: sync map updated on disk after all files processed

pull file:

• success: markdown file written to disk; returns json with keys: file_path, blocks_count, status ("updated")
• failure: raises error with reason (file not tracked, notion page deleted, notion api timeout, etc.)
• side effect: local markdown file overwritten with notion content; sync map unchanged

list tracked pages:

• success: returns list of dicts, each with file_path, page_id, page_url; printed as formatted table
• empty list: if sync map is empty, returns [] with note "no tracked files"

create pipeline db:

• success: returns json with db_id (uuid), db_url (notion.so url), status ("created" or "already_exists"), schema (list of property definitions)
• failure: raises error with reason (parent page not found, api key invalid, etc.)
• side effect: new database page created in notion; database id suitable for use with pipeline_advance.py

pipeline advance:

• success: returns report object with keys:
  • file_path (string)
  • pull_status ("updated" or "no changes")
  • humanizer_changes (list of rules applied)
  • humanizer_diff (path to .humanizer.diff file written)
  • factcheck_report (path to .factcheck.txt file, or "skipped" if script missing)
  • push_status ("created" or "overwritten")
  • new_page_id (uuid)
  • new_page_url (notion.so url)
  • status_advance (string, e.g. "draft -> humanized")
• failure: raises error with reason (file not in pipeline db, slug field missing, etc.)
• side effect: markdown file updated on disk; notion page recreated; pipeline db status field updated; diff and factcheck reports written as .diff and .txt files next to markdown

---

outcome signal

push succeeded: you see ✅ created page or ✅ overwritten page in console output with a valid notion.so url and page id. sync map file updated (check cat ./notion_sync_map.json). opening the notion page shows your markdown content converted to notion blocks (text, headings, code, lists, etc.).

pull succeeded: your local markdown file is overwritten with updated content from notion. file modification timestamp changes. no console errors. if you opened the file in an editor, you see the save prompt or auto-reload.

push-all batch succeeded: console shows summary line like "pushed 5/5 files successfully". sync map contains all file paths as keys. notion parent page shows new child pages for each markdown file.

pipeline advance succeeded: you see report printed to console showing pull, humanize, factcheck, push, and status advance steps. .humanizer.diff file created next to markdown shows all text rules applied. .factcheck.txt created if fact-checker ran. notion page recreated. pipeline db page status changed (e.g., draft → humanized). if --dry-run was used, no files changed on disk or in notion, only proposed actions printed.

list succeeded: table printed showing all tracked files with their notion page urls. you can click each url to open the notion page.

create pipeline db succeeded: console shows new db id and notion.so url. opening the notion parent page shows a new child database titled "content Pipeline" with all required properties visible (slug, platform, status, hook, etc.).

common failure signals:

• 401 unauthorized: api key wrong, expired, or fetched from wrong 1password item. re-run command with correct key.
• 404 not found on parent page: parent page id is wrong or integration was not shared. check notion ui connections panel.
• 400 bad request: annotations object is invalid: markdown annotation parser error. check for nested bold/italic. update to latest notion_content_sync.py (post-2026-03-20).
• notion api timeout: network issue or notion api is slow. retry in 1 minute.
• file not in pipeline db: you pushed to notion parent but not to the pipeline database. manually drag page into pipeline db or re-push with --slug flag.
• page status stuck at approved, n8n not publishing: slug field is empty. set slug in notion manually (format: lowercase hyphens, no spaces). n8n reads this field to build reddi.tech url.

---

reference

scripts included:

• scripts/notion_content_sync.py: push/pull individual files or all at once
• scripts/create_pipeline_db.py: create notion database for content pipeline tracking
• scripts/pipeline_advance.py: full round-trip workflow (pull, humanize, fact-check, push, status update)

quick start commands:

# push single file
python3 scripts/notion_content_sync.py push content/my-post.md

# push all files
python3 scripts/notion_content_sync.py push-all

# pull notion edits back
python3 scripts/notion_content_sync.py pull content/my-post.md

# list all tracked pages
python3 scripts/notion_content_sync.py list

# create pipeline db
python3 scripts/create_pipeline_db.py

# pipeline advance with humanize and fact-check
python3 scripts/pipeline_advance.py advance content/my-post.md

# dry-run (preview only)
python3 scripts/pipeline_advance.py advance content/my-post.md --dry-run

critical 1password credential:

NOTION_API_KEY=$(op read "op://OpenClaw/bg2gpqhpta6an5n4prn2zzycya/credential")

do not use the old item op://OpenClaw/Notion API Key/credential (deleted 2026).

known issues and fixes:

• annotation parser 400 errors (bold/italic at paragraph start): fixed 2026-03-20 in latest script version. ensure you have the latest notion_content_sync.py.
• n8n silently skips approved pages without slug: slug field was missing from db schema (lesson learned 2026-03-28). slug is now required. if a page is stuck at approved and n8n isn't publishing, check that slug property is set and non-empty.
• sync map out of sync after manual notion deletes: handled gracefully. next push will fail 404, auto-create new page, update sync map. do not manually edit sync map json.

database ids (reference):

• content pipeline db: 322eb552-581a-8111-8f6a-d042dd048ec8
• tweet pipeline db: 314c9a82-0734-81be-ac58-ddd878576cf0