🌐 Language: English · 中文

Sanity for Obsidian

Sanity is a plugin for Obsidian that lets you publish and pull documents between your Obsidian vault and your Sanity Studio — a bidirectional sync, not tied to any specific blog or website.

• Write in Obsidian and publish to Sanity as a published document.
• Pull your Sanity documents back into Obsidian to read or edit them.
• Everything is driven by your plugin settings, so it works with whatever schema you have defined.

Installation

This plugin is not on the Community Plugins marketplace. Install it manually or via BRAT.

Option A — BRAT (recommended)

1. Install the BRAT plugin, then add this repository as a beta plugin:

   violet27chen/sanity-obsidian-plugin
   

2. Enable Sanity and open its settings.

Option B — Manual clone

From your vault's root directory:

cd .obsidian/plugins && git clone https://github.com/violet27chen/sanity-obsidian-plugin.git

Restart Obsidian, then enable the plugin in Settings → Installed Plugins.

Understanding your Sanity structure (read this first)

The plugin is completely schema-agnostic — it does not hard-code any field names. Every field name you enter in the settings must come from your own Sanity schema. Before filling the settings, know these four identifiers:

💡 Rule of thumb: anything you type into the plugin settings (type name, title field, body field, GROQ paths in sync rows) must exactly match a name that exists in your Sanity schema. If a field name is wrong, sync silently skips it or the publish fails.

A quick mental model:

• Type name = which kind of document you want to sync.
• Title / Body field = which two fields of that document hold the title and the Markdown body.
• Additional fields to sync = every other field you want to round-trip into the note's frontmatter.

Settings

Open Settings → Sanity. Every field is explained below.

Additional fields to sync — how to fill

This is the most flexible setting. It maps arbitrary Sanity fields into each note's frontmatter (and back on publish). It is empty by default — nothing is synced except the title and body until you add rows.

• Format: one row per field — Sanity field : frontmatter key.
  • Left = the Sanity field name. GROQ paths are allowed, e.g. slug.current, heroImage, social.github.
  • Right = the frontmatter key to map it to. This is the name you want inside the Obsidian note — it does not have to equal the Sanity field name. Leave it blank to reuse the left-side name as the key.
• Up to 10 rows; blank rows are ignored.
• Pull: these Sanity fields are written into the note's frontmatter (image objects become Sanity CDN URLs automatically).
• Publish: the same frontmatter keys are written back to Sanity (CDN URLs are converted back to asset references; local image paths / [[ ]] are uploaded).
• Arrays: a field that is an array in Sanity (e.g. categories[], tags[]) is written back as a YAML list — just write the field name, no special syntax.
• Nested objects: dot-notation paths like slug.current are expanded into nested objects on write (slug: { current: "..." }).
• Image fields: any field whose Sanity value is an image object (e.g. heroImage, avatar, cover) is auto-converted: on pull → a cdn.sanity.io URL in frontmatter; on publish → back to an asset reference (or uploaded if it is a local path).

💡 Cover image vs body images Cover / thumbnail / avatar fields live here as image-object fields (e.g. heroImage:heroImage, avatar:avatar). Body images inside the note (![[image]] or ![alt](image)) are uploaded automatically on publish and do not need a row here.

Blog example (left → right):

slug.current   →   slug
description     →   description
publishedAt     →   published
categories      →   categories
series          →   series
heroImage       →   heroImage

Non-blog example — imagine a Sanity author type with fields name, bio, avatar (image), social (object with github), slug:

avatar         →   avatar
social.github   →   github
slug.current    →   slug

With that, the settings would be: Type name = author, Title field = name, Body field = bio, Filename field = slug.current, and the three rows above. The note's frontmatter would end up with avatar, github, and slug keys — note that github is a custom name you chose for social.github.

Delete all rows (or leave them blank) to sync only the title and body.

Custom API base URL (GFW / proxy)

By default the plugin talks to https://<projectId>.api.sanity.io. In some networks (e.g. mainland China) that host is unreachable while the Sanity CDN (cdn.sanity.io) stays up. Enter a reverse-proxy URL — e.g. https://sanity-api.your-domain.com — and all API calls (query, mutate, upload) route through it. The path after the host is preserved, so nothing else changes. Leave blank to use the default host.

Set up the reverse proxy on EdgeOne (optional)

EdgeOne is a good fit here because its edge nodes are densely distributed across mainland China and the Asia–Pacific — clients in China are served from a nearby node, so latency drops and the Sanity API stays reachable where api.sanity.io is slow or blocked. If you run the proxy on Tencent EdgeOne's edge-acceleration platform, configure these three fields:

⚠️ The Authorization header carries a real Sanity token. Only enable this on a proxy you control, and prefer a token scoped to your project.

Once the proxy is live, paste its URL into Settings → Sanity → Custom API base URL — every query, mutate, and upload call then routes through the edge proxy.

Note frontmatter — what the plugin reads/writes

Body images (![[img]] / ![alt](img)) are uploaded automatically on publish and replaced with CDN URLs — no frontmatter key needed.

Commands

Open the command palette (Ctrl/Cmd + P) and search Sanity:

• Publish to Sanity — create or update the Sanity document for the active note. On success, sanity_id is written to the note. Publishes as a published document and removes any matching draft.
• Pull from Sanity (sync all posts) — pull all published documents of the configured type into Obsidian (drafts are excluded). No open document needed.
• Publish announcement to Sanity — push the Site announcement settings to the siteSettings singleton.

Workflow

Publish a note

1. Fill the note's frontmatter (the title field, and any sync fields you configured — e.g. heroImage, categories, or your custom keys).
2. Put images inline with ![[image]] or ![alt](path).
3. Run Publish to Sanity.
4. The plugin uploads images, sends the document as published, and writes sanity_id into the frontmatter.

Pull everything

1. Run Pull from Sanity (sync all posts).
2. Notes are created/updated in the Pull folder (or vault root), each with sanity_id, sanity_draft, the title, and all configured sync fields.
3. Edit a pulled note and run Publish to Sanity — changes go back to the same Sanity document.

Notes & caveats

• The plugin calls the Sanity HTTP API directly from inside Obsidian, so no CORS configuration is needed in your Sanity project.
• The API token needs Editor (or Admin) role — a read-only token causes 403 insufficientPermissions (update) at publish.
• Publishing creates a published document and deletes the draft if one exists, avoiding duplicate draft/published pairs.
• Pull excludes drafts (drafts.*); it only brings published documents into Obsidian.
• Mobile (Obsidian for iOS/Android) is fully supported; the plugin uses only Obsidian's built-in YAML API, no Node-only packages.
• Use Content divider to publish only the portion of a note above a marker line.

Contributing

Issues and pull requests are welcome.

Acknowledgements

This plugin is a fork of drewlyton/sanity-obsidian-plugin. Many thanks to @drewlyton for the original work this plugin is built upon.