SK-404

Doc no. SK-404DatasheetRev 2026.11Sheet 2.13 of 4

U1

Notion Better Export

Exports a Notion workspace into an Obsidian vault with a true folder hierarchy, resolved relations and native Obsidian Bases.

Shipped

01

Block diagram

Notion APIpages · DBs Pacer2.8 req/s Hierarchytree · UUIDs Markdown CSV .base Atomic writer→ Obsidian vault
Fig. 1: Workspace export pipeline
02

Characteristics

Rate limit2.8 req/s proactive pacing under Notion's 3.0 ceiling; honours Retry-After; circuit breaker after repeated failures
HierarchyReal parent/child folders; Page.md sits next to its Page/ folder; linked database views point at one canonical copy
LinksTwo-pass resolution turns relation UUIDs into titles and [[wikilinks]] across CSVs and frontmatter
ViewsNotion table, list, board and gallery views compiled to Obsidian .base files (board and gallery become card views) and embedded live
SafetyAtomic writes, single-instance lockfile, dry-run, refuses to write into system or home directories
Offline repairnbe fix repairs raw UUIDs in an existing export without the API, with backups
Tests140 unit tests, all passing
  • Python
  • Notion API
  • httpx
  • PyYAML
  • Rich
  • Obsidian Bases
03

Overview & build notes

Notion's stock zip export flattens sub-pages with hex ID suffixes and leaves relational database columns full of raw UUIDs. nbe reads your workspace directly through a read-only Notion integration token, rebuilding clean parent/child folders and deduplicated database views.

Every workspace pass runs in two phases: first discovering all databases, pages and child trees via client.py (paced at 2.8 req/s under Notion's API cap), then compiling Markdown files, linked CSVs and native Obsidian .base views while rewriting UUID references into clean [[wikilinks]].

An export manifest lets nbe fix patch broken relation links in an existing vault offline with automatic backups, and atomic file replacement plus path safety checks protect destination folders.

04

Files & artifacts

KindFileDetailsSize
Sourcenotion_better_export/exporter.pyTwo-pass Notion API traversal, hierarchy builder and database serializer on GitHubGitHub
Sourcenotion_better_export/base_exporter.pyCompiles Notion table/board/gallery views into Obsidian .base definitionsGitHub
Docsdocs/ARCHITECTURE.mdRate limiter design, manifest format and link-resolution stages on GitHubGitHub
Docsdocs/CLI_REFERENCE.mdCommand flags for nbe init, nbe auto, nbe fix and --dry-runGitHub

A4Odysseus Notion Skill