Vault to Notion

Publish your Obsidian notes to Notion — as a page tree that mirrors your vault, or as rows of a database — and keep them updated in place.

Your vault in Obsidian → the same structure in Notion (page tree mode):

📁 Projects
   📁 Website
      📝 Launch plan
      📝 SEO checklist
   📝 Ideas
📝 Reading list

📄 Obsidian Vault
   📁 Projects
      📁 Website
         📄 Launch plan
         📄 SEO checklist
      📄 Ideas
   📄 Reading list

Contents

• Features
• How it works
• Requirements
• Installation
• Configuration
  • 1. Create a Notion API token
  • 2. Prepare the destination in Notion
  • 3. Give your connection access
  • 4. Configure the plugin
  • Settings reference
• Usage
• What happens when…
• Markdown conversion
• Troubleshooting
• Limitations
• Network use and privacy
• Development
• License

Features

• Two publishing modes
  • Page tree (default) — folders and notes become pages in the Notion sidebar, exactly like your vault. Needs a single Notion page link.
  • Database — notes become rows of a Notion database with optional Tags and Folder columns for filtering, sorting and grouping; optionally also a folder tree in which every folder page shows a filtered table of its notes.
• Updates in place. Publishing again updates the same Notion page, so its link and comments survive. A note moved to another folder has its page moved too (page tree mode).
• Whole-folder publishing. Right-click any folder. Unchanged notes are skipped without re-uploading, and pages deleted in Notion are recreated.
• Obsidian-aware conversion to Notion's own Markdown format: callouts, highlights, task lists, tables, code, math — while %% comments %% stay private.
• Built on Notion's current API (2026-03-11): the markdown content API, data sources, views and page moves, with rate-limit handling as Notion recommends.
• Works on desktop and mobile, from the ribbon, the command palette or the file explorer's context menu.

How it works

flowchart LR
    A[Obsidian note] -->|strip frontmatter and private comments,<br/>convert to Notion-flavoured Markdown| B(Vault to Notion)
    B -->|no notion_id yet| C[Create page]
    B -->|notion_id in frontmatter| D[Update the same page]
    B -->|content unchanged and page still exists| E[Skip]
    C --> F[(Notion)]
    D --> F
    C -->|write notion_id + notion_url| A

The plugin talks to the Notion REST API directly from Obsidian. Note content is sent with Notion's markdown content API in Notion-flavoured Markdown. Which page belongs to which note is stored in the note itself (notion_id in the frontmatter), so it travels with the note across devices.

Requirements

• Obsidian 1.13.0 or later (desktop or mobile).
• A Notion account, and a Notion API token — see step 1.

Installation

From Obsidian (once listed in the community directory): Settings → Community plugins → Browse, search for Vault to Notion, then Install and Enable.

With BRAT (beta versions): install the BRAT plugin, choose Add beta plugin, and enter this repository's URL.

Manually: download main.js and manifest.json from the latest release into <your vault>/.obsidian/plugins/vault-to-notion/, reload Obsidian, and enable Vault to Notion under Settings → Community plugins.

Configuration

Setup takes about five minutes. You only do it once per vault.

1. Create a Notion API token

Notion offers two kinds of tokens that work with this plugin. Both start with ntn_.

The internal connection is recommended because it can only see what you explicitly share with it — the least access the plugin needs.

Create an internal connection

1. Open the Developer portal and select the Connections tab ①.

   

2. Create a new connection: enter a Connection name such as Obsidian Sync ①, keep API token as the authentication method ②, and click Create connection ③. OAuth is meant for apps used by other people's workspaces and is not needed here.

   

3. On the connection's Configuration tab:

   • ① Copy the API token under Integration token with the copy button. Keep it secret: anyone with the token can act on behalf of the connection.
   • ② Under Content capabilities, keep Read content, Update content and Insert content checked.
   • ③ Under User capabilities, choose No user information — the plugin never reads user data, so it is best not to grant it.

   

   Why each capability is needed (see Notion's capabilities reference):

   Capability	Used to
   Read content	Check that pages exist and read the database's columns
   Update content	Update published pages and move them between folders
   Insert content	Create pages, folder pages and folder tables

Or create a personal access token: in the same Developer portal, select the Personal access tokens tab, click New token, give it a name, select the Notion API capability, and create it. Copy the token right away — it is shown only once (guide).

2. Prepare the destination in Notion

Tip: put the database inside your "Obsidian Vault" page. Access given to a page also covers everything inside it, so you only share once.

3. Give your connection access

Skip to "Copy the link" if you use a personal access token.

An internal connection cannot see anything until you give it access. Access to a page also covers everything inside it, as Notion's capabilities reference notes, so sharing your "Obsidian Vault" page once is enough.

In the Developer portal — open your connection, select the Content access tab ①, and click Edit access ②:

Tick the page from step 2 ① and click Save ②:

Or from Notion itself — open the page, click ••• → Connections → + Add connection, and choose your connection. Both ways are described in Notion's internal connections guide.

Copy the link — open the page (or database), click ••• ① → Copy link ②, or press Ctrl+Alt+L:

Links look like https://app.notion.com/p/Obsidian-Vault-3f31…. The plugin reads the ID from any Notion link, including older notion.so links.

4. Configure the plugin

Open Settings → Vault to Notion:

1. In API token ①, click Change and create a secret holding your token (or pick one you saved before). Obsidian keeps it in its secret storage, not in the plugin's settings file, and other plugins can reuse the same secret.
2. Choose Publish as ②: Page tree or Database.
3. Paste the link from step 3 into Root page ③ (page tree) or Database (database).
4. Click Test ④. You should see Connected to "Obsidian Vault". If not, the message explains what to fix — see also Troubleshooting.

In Database mode, a Columns section with the tag and folder options appears below Test connection.

Settings reference

Usage

To publish a whole folder, right-click it in the file explorer and choose Publish folder to Notion ①:

After the first publish, two properties are added to the note's frontmatter:

notion_id: 1a2b3c4d-5e6f-4a1b-9c2d-3e4f5a6b7c8d
notion_url: https://app.notion.com/p/My-note-1a2b3c4d5e6f4a1b9c2d3e4f5a6b7c8d

notion_id links the note to its page — keep it to update the same page next time, or delete it to publish a fresh copy. Publishing a folder with more than 20 notes asks for confirmation first, and ends with a summary such as 12 created, 3 updated, 85 unchanged.

What happens when…

Markdown conversion

Notes are converted to Notion-flavoured Markdown before upload.

Troubleshooting

Click Test in the settings first — it checks the token and the destination without publishing anything.

Technical details of failures are written to the developer console (View → Toggle Developer Tools), prefixed with [Vault to Notion].

Limitations

• Local images, attachments and embeds are not uploaded yet.
• Links between notes become plain text rather than links between Notion pages.
• Publishing is one-way: changes made in Notion are not brought back into Obsidian.
• Deleting notes or folders in Obsidian does not delete their Notion pages.

Network use and privacy

This plugin connects to one remote service: the Notion API at api.notion.com. It is used to read the page or database you configure and to create, update and move pages there. The plugin sends the content of the notes you publish — nothing else, and only when you publish. There is no telemetry and no other server involved.

What the plugin accesses on your device:

• Notes: only the note you publish, or the notes inside the folder you publish. It does not scan the rest of the vault. It writes notion_id and notion_url into the frontmatter of the notes it publishes.
• Clipboard: after publishing a single note it writes the page's link to the clipboard. It never reads the clipboard. Turn off Copy link after publishing to disable this.

Your API token is kept in Obsidian's secret storage on this device, not in the plugin's data.json, so it does not end up in vault backups, sync or Git. Secret storage is not synced between devices: on another device, add the token once more in the settings. Tokens saved by earlier builds in data.json are moved into secret storage automatically.

Development

npm install
npm run dev     # rebuild main.js on every change
npm run build   # type-check and build for production
npm run lint    # Obsidian's official lint rules (eslint-plugin-obsidianmd)

Copy main.js and manifest.json into <vault>/.obsidian/plugins/vault-to-notion/ and reload the plugin.

Releasing: run npm version <x.y.z> and push the tag. The GitHub workflow lints and builds the plugin, signs build provenance attestations for the release files, and attaches main.js and manifest.json to a release named after the version. To check that a downloaded main.js was built from this repository:

gh attestation verify main.js --repo thanhan1997tr/vault-to-notion

License

MIT © 2026 An Tran Solutions — see LICENSE.

Inspired by Obsidian shared to Notion by EasyChris.