AgentSkillsCN

notion-obsidian-sync

使用 notoma 将 Notion 工作空间同步至 Obsidian 仓库。当用户希望同步 Notion 数据、导入 Notion 页面、将 Notion 导出至 Obsidian，或备份 Notion 数据为 Markdown 格式时，可使用此工具。

SKILL.md
--- frontmatter
name: notion-obsidian-sync
description: Sync Notion workspace to Obsidian vault using notoma. Use when the user asks to sync notion, import notion pages, export notion to obsidian, or back up notion to markdown.
metadata:
  version: 1.0.0

Notion → Obsidian Sync

Incremental sync of your Notion workspace to Obsidian as Markdown, using notoma for conversion with .base files, attachments, and state tracking.

Trigger Phrases

  • •"sync notion to obsidian"
  • •"import notion"
  • •"notion sync"
  • •"back up notion"
  • •"export notion to obsidian"
  • •"download my notion pages"

Prerequisites

  1. •Go 1.24+: For building notoma from source
  2. •1Password CLI: Notion API token stored in item Notion, field API Key
  3. •Obsidian Vault: At ~/Obsidian/cag/ (output goes to Notion/ subfolder)

First-Time Setup

  1. •Create a Notion integration at https://www.notion.so/profile/integrations
  2. •Copy the Internal Integration Secret
  3. •Store it in 1Password: item Notion, field API Key
  4. •Share desired Notion pages/databases with the integration

Quick Run

bash
# Incremental sync (uses saved state)
bash skills/notion-obsidian-sync/assets/sync.sh

# Full re-sync (ignore state, re-download everything)
bash skills/notion-obsidian-sync/assets/sync.sh --force

# Preview without writing files
bash skills/notion-obsidian-sync/assets/sync.sh --dry-run

Workflow

  1. •Retrieve Notion API token from 1Password (op item get "Notion" --fields "API Key" --reveal)
  2. •Build notoma if binary not cached in data/notoma (clone repo + go build)
  3. •Generate runtime config from assets/config.yaml with absolute paths
  4. •Run data/notoma sync --config <runtime-config>
  5. •Report results (pages synced, attachments downloaded, errors)

Output

Directory: ~/Obsidian/cag/Notion/

  • •Markdown files for each Notion page
  • •_attachments/ subfolder for images and files
  • •State tracked in data/notoma-state.json for incremental sync

Configuration

The config template lives at assets/config.yaml. The sync script copies it at runtime and resolves relative paths to absolute ones. Key settings:

SettingValuePurpose
discover_workspace_rootstrueAuto-discover all shared pages
vault_path~/Obsidian/cag/NotionObsidian output directory
attachment_folder_attachmentsSubfolder for downloaded files
download_attachmentstrueFetch images and file blocks

Error Handling

ErrorCauseRecovery
NOTION_TOKEN not set1Password retrieval failedVerify item Notion exists with field API Key
go: command not foundGo not installedInstall Go 1.24+ via brew install go
Build failureNetwork or Go module issueDelete data/notoma-src/ and retry
401 UnauthorizedToken invalid or integration not sharedRe-check integration token and page sharing
State corruptionInterrupted syncDelete data/notoma-state.json and run --force

Notes

  • •Binary and state files live in data/ (gitignored via **/data/ pattern)
  • •notoma is built from source once and cached; delete data/notoma to force rebuild
  • •The --force flag deletes the state file before syncing, triggering a full re-download
  • •Safe to run repeatedly — notoma's state tracking makes syncs incremental