Sanity Integration

Connect your Sanity project to publish articles written in Asky straight into your content lake, as real documents of your own type, with your own fields.

What You Get

Prerequisites

• A Sanity project and dataset
• A robot token with Editor permission (sanity.io/manage  → your project → API → Tokens)
• Your schema deployed to the dataset (see below)

Deploying your schema

Asky reads your deployed schema to know which document types exist and what fields they have. This is the one setup step that is not inside Asky:

npx sanity schemas deploy

Run it from your Studio project. Without it, Asky can connect but has no types to offer.

It needs re-running whenever your schema changes, which is worth automating: see Keeping your schema in sync below.

Keeping your schema in sync

This is the one step that isn’t inside Asky, and the one most likely to be forgotten, so it’s worth understanding why it exists.

Three things in Sanity are more independent than they look:

• The Content Lake is schemaless. Documents are just JSON. Changing a schema doesn’t migrate or validate existing content.
• Your site queries the dataset with GROQ, and GROQ never reads the schema. A schema change has no effect on your live site by itself.
• Your Studio is where a schema change lands for editors, and that happens when you rebuild and redeploy the Studio.

sanity schemas deploy is none of those. It writes a machine-readable description of your content model into the dataset, and Asky is what reads it.

What happens if it’s stale

Asky shows how long ago your schema was deployed, and after a publish it samples your real documents to tell you when they contain fields the deployed schema doesn’t.

Automate it in CI

Running it by hand works. Automating it means it can’t be forgotten.

A Sanity-hosted Studio deployed with sanity deploy extracts the schema as part of that command. A self-hosted Studio (Vercel, Netlify, your own CI) usually builds with sanity build, which does not write to the dataset, so it needs the extra step.

Add it to your build command:

sanity build && sanity schemas deploy

Or as its own GitHub Actions step:

- name: Deploy Sanity schema
  run: npx sanity schemas deploy
  env:
    SANITY_AUTH_TOKEN: ${{ secrets.SANITY_AUTH_TOKEN }}

CI needs its own token with deploy permission, set as SANITY_AUTH_TOKEN. This is separate from the token you gave Asky, and it doesn’t need to be the same one.

Connecting Sanity

Publishing

Open any draft in the Content Library, choose Sanity as the destination, pick a document type, and fill in the fields. Then Publish Now, or Save as Draft to CMS to leave it unpublished in Studio.

Asky writes only the fields it manages. Anything an editor set in Studio (SEO objects, contributors, related posts, an image hotspot) is left untouched, because Asky patches rather than replaces the document.

Links

Portable Text has no built-in link type; each schema declares its own annotation. Asky asks which one is your external link during setup and shows the resolved path in the publishing panel. If your rich text has no annotation that can hold a link, Asky blocks publishing for any article containing one rather than silently dropping the hrefs.

Images

Images in the article are uploaded into your own asset store and referenced normally. Sanity content-addresses assets, so republishing the same image does not create duplicates.

Two things about your schema decide how much survives, and the publishing panel tells you both before you publish:

• If the rich text field declares no image member, pictures cannot be stored at all and are dropped. Everything else still publishes.
• If the image member declares no alt field, the picture publishes and the alt text is dropped, because Asky writes alt only where your schema has somewhere to put it. It looks for alt, altText or alternativeText, and deliberately never repurposes caption or attribution — those render as visible text on your site, so filling one with an alt attribute would add a caption you never wrote.

A bare defineArrayMember({type: 'image'}) is Sanity’s default and declares neither, so adding an alt field is usually a one-line change:

defineArrayMember({
  type: 'image',
  fields: [defineField({name: 'alt', type: 'string', title: 'Alt text'})],
})

Either way the publish report names what was dropped, so this never happens quietly.

Translations

With @sanity/document-internationalization, each language is its own document with a language field, joined by a translation.metadata document.

That is exactly how Asky models translations, so each language publishes independently. A language joins the switcher when it goes live, which also avoids Sanity’s rule that a document cannot publish while it references an unpublished one. See Translations for how a language version is created in the first place.

Editing in both places

Asky is a one-way publisher: it writes to Sanity, and does not read your Studio edits back into the draft.

If a document changed in Studio since Asky last published it, Asky says so before you republish. Sanity also rejects the write server-side if the document changed while the publish was in flight, so a genuine race fails loudly instead of quietly overwriting someone.

Troubleshooting