/notion-wiki-from-vault

Obsidian → Notion, one-way. Lets users keep working in Obsidian (their canonical store per obsidian_auto_logging.md) while exposing curated subsets to Notion-based stakeholders.

Inputs

• Source folder (required). Path under ~/Obsidian/ to sync. e.g. Projects/STUDIO/web-design-service/ or Brands/ExampleBrand-co/brand-identity/.
• Target Notion parent (required). URL or ID of the Notion page that should hold the synced pages.
• Scope (optional). Default: all .md files in the source folder (non-recursive). User can pass "recursive" to include subfolders, or "files: a.md, b.md" to scope explicitly.
• Frontmatter mapping (optional). If user wants Obsidian frontmatter fields mapped to Notion page properties (only works if target parent is a database, not a regular page). Default: ignore frontmatter.

Steps

1. Index vault folder. List .md files in scope. Parse each: frontmatter, body, wikilinks, embeds, tags.
2. Index Notion target. notion-fetch the parent. List existing child pages (these are previous sync outputs if any).
3. Diff.

• New files → create as new Notion sub-pages.
• Existing files (matched by title) → diff content. If changed, update via notion-update-page replace_content.
• Notion pages with no matching vault file → flag, never auto-delete. User decides.

1. Convert content per file.

• Frontmatter: strip from body. If target is a database, map fields to properties; otherwise drop with a comment header on the Notion page ("Source: <vault path>. Synced YYYY-MM-DD.").
• Wikilinks [[note-name]] → Notion link to the corresponding synced page (lookup by title in this batch + target parent). Unresolvable wikilinks → keep as plain text "note-name" + note in sync report.
• Embeds ![[image.png]] → upload image to Notion if it exists at ~/Obsidian/<folder>/<image> (via notion-upload-image or upload_assets MCP tool). Otherwise keep as text reference.
• Callouts > [!note] → Notion callout block.
• Tasks - [ ] → Notion to-do block.
• Code blocks → Notion code block (preserve language).

1. Dry-run report. Before writing:

• N new pages to create
• M existing pages to update
• K Notion pages with no vault match (no action)
• Unresolved wikilinks list
• Image-upload count

1. Confirm gate. Wait for "go".
2. Sync.

• Create new pages with notion-create-pages.
• Update existing with notion-update-page (replace_content with the new converted markdown, preserving child sub-pages).
• Upload images via the appropriate tool.

1. Write a sync log to ~/Obsidian/<source-folder>/.notion-sync-log.md (gitignored if vault is in git). Records what synced, when, to where, and any unresolved items.
2. Confirm. Print pages created/updated with URLs.

One-way: never reverse-sync

Vault is canonical. If a Notion page diverges, user must reconcile by editing the vault file. This skill never writes Obsidian. Document this loudly in the sync log header so collaborators see it.

Decision rules

• Match by title, not slug. Notion pages use title as the user-facing identifier.
• Frontmatter is metadata, not body. Never render raw frontmatter into Notion as visible text. Strip or map to properties.
• Preserve child Notion pages. If a user created additional sub-pages under a synced page in Notion, notion-update-page with replace_content must include them (the tool errors if not — use the <page url="..."> preservation tags).
• Image dedup. Upload an image once even if it's referenced in N notes — track upload IDs.

Anti-patterns

• Don't sync the entire ~/Obsidian/ root. Always require a scoped folder.
• Don't auto-delete Notion pages with no vault match. Surface them; let the user delete manually.
• Don't sync notes with status: paused or status: archived frontmatter — skip them, list in the report.
• Don't sync the Inbox/ folder by default — it's noisy, ephemeral.

Hard-won gotchas

• Wikilinks resolve in batch context. If note-a.md links [[note-b]] and both are in this sync batch, resolve to note-b's Notion URL. If note-b was synced in a previous run and exists under the target parent, also resolve. Otherwise leave as plain text.
• Title collisions. If two vault files share a title (different folders), they'll collide on Notion. Surface in the dry-run and ask for disambiguation.
• Notion markdown is not vault markdown. Notion's enhanced markdown spec is at notion://docs/enhanced-markdown-spec. Fetch it before composing if uncertain about block syntax.
• Update via `replace_content` can delete child pages — must include them in new_str via <page url="..."> tags. Read the parent's current content before composing the update.

Output

• Dry-run report.
• After sync: list of pages created/updated with URLs.
• Sync log appended to the vault folder.