Doc no. SK-404DatasheetRev 2026.11Sheet 2.13 of 4
Notion Better Export
Exports a Notion workspace into an Obsidian vault with a true folder hierarchy, resolved relations and native Obsidian Bases.
Shipped
Source on GitHub
$ nbe auto --dry-run
Block diagram
Characteristics
| Rate limit | 2.8 req/s proactive pacing under Notion's 3.0 ceiling; honours Retry-After; circuit breaker after repeated failures |
|---|---|
| Hierarchy | Real parent/child folders; Page.md sits next to its Page/ folder; linked database views point at one canonical copy |
| Links | Two-pass resolution turns relation UUIDs into titles and [[wikilinks]] across CSVs and frontmatter |
| Views | Notion table, list, board and gallery views compiled to Obsidian .base files (board and gallery become card views) and embedded live |
| Safety | Atomic writes, single-instance lockfile, dry-run, refuses to write into system or home directories |
| Offline repair | nbe fix repairs raw UUIDs in an existing export without the API, with backups |
| Tests | 140 unit tests, all passing |
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.
Files & artifacts
| Kind | File | Details | Size |
|---|---|---|---|
| Source | notion_better_export/exporter.py | Two-pass Notion API traversal, hierarchy builder and database serializer on GitHub | GitHub |
| Source | notion_better_export/base_exporter.py | Compiles Notion table/board/gallery views into Obsidian .base definitions | GitHub |
| Docs | docs/ARCHITECTURE.md | Rate limiter design, manifest format and link-resolution stages on GitHub | GitHub |
| Docs | docs/CLI_REFERENCE.md | Command flags for nbe init, nbe auto, nbe fix and --dry-run | GitHub |