Sanity
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
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
projectIdin yoursanity.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
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),bodyorcontent(Portable Text),excerpt,mainImageorcoverImage(image),seoTitleandseoDescription,tags(array of strings) andpublishedAt(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:datetimeEach entry is
name:type, separated by commas or new lines. Types arestring,text,slug,blockContent(Portable Text),image,url,datetime,date,boolean,number,array:stringandreference:author(a reference to a document of that type). Fields inside an object are written asseo.metaTitle:string. - 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
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
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
altfield. Re-uploading the same image reuses the existing asset. - Code blocks. Written as
codeblocks in the shape of the@sanity/code-inputplugin. 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.