Skip to content
SF CTA Study Hub

Notion Sync Guide

Overview

Notion serves as the cloud-accessible mirror of the local docs/ content — useful for cross-device access, sharing, and reading study notes from any browser. This is different from Obsidian: Obsidian IS the files (zero sync needed, since it reads directly from docs/), while Notion requires pushing copies of the content via an API.

Two approaches are available depending on your needs:

  • go-notion-md-sync — CLI tool, bidirectional sync, watch mode; recommended when you want all 15 docs in Notion and kept up to date
  • Notion MCP — already connected in Claude Code with 14 tools; no API key configuration needed; best for ad-hoc pushes and querying individual pages

For the local editing experience, see Obsidian Setup Guide.

Approach 1 — go-notion-md-sync (Recommended for Full Sync)

Install

Terminal window
curl -sSL https://raw.githubusercontent.com/byvfx/go-notion-md-sync/main/scripts/install-unix.sh | bash

Verify the install succeeded:

Terminal window
notion-md-sync --version

Get your credentials

Before running any sync commands, you need two values: a Notion integration secret and a root page ID.

  1. Go to notion.so/profile/integrations
  2. Click New integration, name it CTA Study Sync, set type to Internal
  3. Copy the Internal Integration Secret — this is your NOTION_API_KEY
  4. Open Notion in your browser and create a new page called CTA Study Hub at the top level of your workspace
  5. Open that page, click the ”…” menu in the top-right corner, then go to Connections and add your CTA Study Sync integration
  6. Copy the page ID from the URL: notion.so/{workspace}/{PAGE_ID} — this is your NOTION_PAGE_ID

Configure environment

Terminal window
export NOTION_API_KEY="secret_xxxx"
export NOTION_PAGE_ID="your-page-id-here"

Add both lines to ~/.zshrc (or ~/.zprofile) to persist across sessions:

Terminal window
echo 'export NOTION_API_KEY="secret_xxxx"' >> ~/.zshrc
echo 'export NOTION_PAGE_ID="your-page-id-here"' >> ~/.zshrc
source ~/.zshrc

Create the Notion workspace structure

Before the first push, create child pages inside CTA Study Hub that match the docs/ folder layout. go-notion-md-sync maps local folders to Notion sub-pages by name.

  • CTA Study Hub (root page — already created above)
    • 01 - System Architecture
    • 02 - Security
    • 03 - Data Architecture
    • 04 - Solution Architecture
    • 05 - Integration
    • 06 - Development Lifecycle
    • 07 - Communication
    • Resources

Create each child page manually in the Notion UI before running the first push.

Sync commands

Terminal window
# Push all local content to Notion
notion-md-sync push /Users/vj/Office/sf-cta-study/docs/


# Pull Notion changes back to local files
notion-md-sync pull /Users/vj/Office/sf-cta-study/docs/


# Watch mode — auto-sync on file save
notion-md-sync watch /Users/vj/Office/sf-cta-study/docs/


# Push a single file
notion-md-sync push /Users/vj/Office/sf-cta-study/docs/05-integration/index.md

Limitations to know

  • [[wikilinks]] appear as plain text in Notion — Notion does not support the wikilink format; they are not hyperlinks
  • YAML frontmatter is preserved via go-notion-md-sync’s internal tracking: after the first push, it stores the Notion page ID in each file’s frontmatter (consider adding these IDs to .gitignore or committing them — your choice)
  • Pages over ~20,000 blocks may be truncated; none of the current docs/ files approach this limit
  • The first push of all 15 files can take a few minutes

Approach 2 — Notion MCP (Already Connected, Zero Setup)

The Notion MCP is already connected in Claude Code with 14 tools. No API key configuration, no extra install — it works right now.

Use cases for the MCP approach:

  • Push a single page: Ask Claude “Use notion-create-pages to push the content of docs/05-integration/index.md to my Notion workspace”
  • Query existing Notion content: Ask Claude “Use notion-search to find my Notion pages about integration patterns”
  • Update a specific page: Ask Claude “Use notion-update-page to update the integration page with this new content”
  • Retrieve a page: Ask Claude “Use notion-fetch to get the current content of my System Architecture Notion page”

Key MCP tools:

ToolPurpose
notion-create-pagesPush a page with Notion-flavored Markdown
notion-fetchRetrieve full page content as Markdown
notion-searchSearch across your workspace
notion-update-pageUpdate content (search-and-replace or full replace)
notion-duplicate-pageDuplicate a page
notion-move-pagesMove pages/databases
notion-create-databaseCreate databases using SQL DDL syntax
notion-create-viewCreate table/board/calendar/chart views
notion-create-commentAdd comments to pages
notion-get-commentsRetrieve discussion threads
notion-get-teamsList teamspaces
notion-get-usersList workspace members

The MCP is best for one-off operations. For keeping all 15 docs in sync continuously, use go-notion-md-sync instead.

Sync Strategy Recommendation

NeedApproach
Initial full push of all 15 docsgo-notion-md-sync push
Keep Notion current while editing locallygo-notion-md-sync watch
Push a single updated filego-notion-md-sync push docs/path/to/file.md
Pull Notion edits back to localgo-notion-md-sync pull
Query Notion from ClaudeNotion MCP (notion-search, notion-fetch)
Create a new Notion page from ClaudeNotion MCP (notion-create-pages)
Update a specific page from ClaudeNotion MCP (notion-update-page)