SanitySanity

Publish SiteLift articles as documents in your Sanity dataset, with the body as Portable Text, images uploaded as assets and your own fields mapped.

How it works

SiteLift writes each article as a document of the type you choose (usually post) in your Sanity project, using an API token with the Editor role. You match SiteLift’s fields to the fields of that document type once; every article is then written as a published document, and republishing an edited article updates the same document instead of creating a new one. Your Studio and your frontend see it like any document an editor published.

Setup Guide

  1. 1

    Create an API token

    Open sanity.io/manage and pick your project. The project id is the short code under the project name (it is also projectId in your sanity.config.ts).

    Go to Settings → API → Tokens and click Add new token. Name it SiteLift, give it the Editor role and save. Copy the token right away: Sanity shows it only once. A Viewer token can read but not write, so publishing fails with it.

    Note the dataset your Studio uses, listed under Datasets. Most projects use production.

  2. 2

    Prepare the document type

    SiteLift publishes into an existing document type from your Studio schema, typically post. These field names are mapped automatically: title, slug (slug type), body or content (Portable Text), excerpt, mainImage or coverImage (image), seoTitle and seoDescription, tags (array of strings) and publishedAt (datetime). Other names can be mapped by hand.

    Sanity keeps the schema in your Studio code, not in the dataset, so SiteLift learns the fields in this order: from a field spec you paste, from the schema deployed with npx sanity schemas deploy, or from the documents of that type already in the dataset. On a new, empty dataset paste a field spec when you connect, for example:

    title:string, slug:slug, body:blockContent, mainImage:image, excerpt:text,
    seoTitle:string, seoDescription:text, publishedAt:datetime

    Each entry is name:type, separated by commas or new lines. Types are string, text, slug, blockContent (Portable Text), image, url, datetime, date, boolean, number, array:string and reference:author (a reference to a document of that type). Fields inside an object are written as seo.metaTitle:string.

  3. 3

    Connect and map the fields

    In SiteLift open Settings → Integrations, choose Sanity, and enter the project id, dataset and token, plus the field spec if you have one. SiteLift lists the document types it finds in the dataset; pick the one your posts use. If the dataset has no documents yet, type the document type name in the connection form.

    Check the proposed mapping and adjust it. Reference fields such as an author take a fixed document picked from a list. The test publish writes a draft document, lets Sanity accept it, and deletes it again.

  4. 4

    Publish

    Articles publish on your content calendar schedule as published documents, not drafts. If your frontend builds statically, trigger a rebuild from a Sanity webhook as you would for an editor’s change. To get links back to the live article in SiteLift, set the public URL pattern, such as https://example.com/blog/{slug}; without it SiteLift stores no URL.

Tip

Once connected you never log into Sanity to publish. Articles go live on your SiteLift schedule, and edits made in SiteLift are pushed again when you republish.

What gets published

  • Body as Portable Text. The article HTML is converted to Sanity blocks: headings H2 to H4, paragraphs, bold, italic, inline code, links, bulleted and numbered lists (with nesting) and blockquotes. Tables become one paragraph per row; horizontal rules are dropped.
  • Images. The featured image and every image in the body are uploaded to your project as image assets and referenced, with their alt text in an alt field. Re-uploading the same image reuses the existing asset.
  • Code blocks. Written as code blocks in the shape of the @sanity/code-input plugin. Install the plugin and add { type: 'code' } to your body field, or the Studio shows them as unknown blocks.
  • Title and featured image. They go into their own fields, so the H1 and hero image are removed from the body.
  • Structured data. The JSON-LD is available as its own SiteLift field; map it to a text field and print it in your page head.
  • Fields SiteLift does not map. Kept on republish, so an author or categories an editor sets in the Studio stay in place.

Competitor comparison pages

Supported as blog posts in your existing Sanity document type, using the same connection and field mapping as your articles. They use the same blog layout and feed as your articles. No extra collection, content model, template or comparison mapping is needed. Existing supported tag or category fields can group them as Comparisons; no new field is required. SiteLift does not create a separate comparison hub or add a link to one. The blog controls the URLs, so the comparison URL prefix does not apply.

Troubleshooting

  • 401 from Sanity. The token is wrong or was deleted. Create a new one under Settings → API → Tokens in sanity.io/manage and reconnect.
  • 403 or “Insufficient permissions”. The token has the Viewer role or a custom role without create rights. Create a token with the Editor role.
  • 404 “Dataset not found”. The project id or dataset name has a typo. Both are lowercase; copy them from sanity.io/manage.
  • SiteLift asks for a field spec. The dataset has no documents of that type and no deployed schema. Paste a field spec in the connection form, or run npx sanity schemas deploy in your Studio project and connect again.
  • The Studio shows “unknown field” on published articles. A mapped field name does not exist in your Studio schema. Fix the field spec or the mapping so the names match your schema exactly; field names are case sensitive.

Still stuck? Use Test Connection on the Integrations page; the message comes straight from Sanity. Or write to support.