In the Astro + Sanity edition, stories, sections, reporters, the front page picks, and the site settings live in Sanity, and your newsroom writes in Sanity Studio, an editor that runs in the browser. The site is still static: it reads published content when it builds, so it’s as fast as the Astro edition. For the pages, settings, and components both editions share, see the Blakey overview.
How the connection works
The site finds your content with two values: a project ID and a dataset name. They aren’t secrets. They let anyone read what you’ve published, which is what your site shows anyway. Drafts are never public.
Tokens are the secrets (for example, one that can read drafts). The theme ships with no project ID and no tokens. Setup creates a project in your own Sanity account and writes its ID to .env files that are never committed. Nobody else, including us, has access to your project.
Setup
You need a free Sanity account. In the theme folder:
npm install
npm run setup
Setup:
- Installs the Studio’s dependencies in
studio/. - Logs you in to Sanity if needed. A browser window opens.
- Creates a project with a public
productiondataset, or uses the one already in.env. - Writes the project ID and dataset to
.envandstudio/.env, keeping anything else in those files. - Imports the demo content: 12 stories, 6 sections, 6 reporters, the front page, Site settings, and their images.
- Allows the local Studio (
http://localhost:3333) to talk to the project.
| Option | Effect |
|---|---|
--name "My Newsroom" |
Name for the new project |
--project <id> |
Use an existing project instead of creating one |
--dataset <name> |
Use another dataset; it’s created if missing |
--no-seed |
Skip the demo content |
--yes |
Accept every default without asking |
Pass options after --, for example npm run setup -- --no-seed. Running setup again is safe; existing content is kept.
Then npm run dev shows the site at http://localhost:4321. If .env has no project ID, dev and build stop with a message pointing to npm run setup.
Writing in the Studio
npm run studio # http://localhost:3333
| Document | Fields |
|---|---|
| Story | Headline, slug, dek, lead image with alt text, caption, and credit, body, section, byline (one or more reporters), format, date, updated date, tags, featured, reading progress bar, and an SEO tab (title, description, social image, hide from search engines) |
| Section | Title, slug (the URL), description, order |
| Reporter | Name, slug (the URL), role, bio, photo, location, email, profile links, order |
| Front page | Lead story, Most read, The Big Story, Editors’ Picks. There’s one per site; see Front page |
| About | Intro, lead image, story, masthead, and standards for /about/. There’s one per site; see About |
| Site settings | Contact details, masthead, footer, SEO, AI and search, analytics. There’s one per site; see Site settings |
- Stories by section in the Studio’s menu lists each section’s stories, newest first.
- Format sets the label above the headline and the structured data type. See Story formats.
- Reading progress bar left unset follows
story.progressBarinsrc/config/pages.ts. - The body supports headings, quotes, lists, bold, italic, code, links, and images with captions.
- Lower order numbers come first in section lists and on the reporters page.
Images: after uploading, click Edit and drag the hotspot onto the subject. Cards, social images, and search thumbnails crop images to different shapes, and the hotspot keeps the subject in view. Sanity serves every image in the sizes and formats each page needs.
Hide from search engines on a story adds noindex and also leaves the story out of the sitemap, site search, llms.txt, llms-full.txt, its Markdown version, and the structured data endpoint. It still shows on the site and in RSS.
To add a field, change the schema in studio/schemaTypes/, then add it to the query and types in src/lib/stories.ts. The repo’s docs/SANITY.md has the details.
Front page
The Front page document lets the desk program the home page without touching code. Anything left empty falls back:
| Field | Band | Left empty |
|---|---|---|
| Lead story | The top story, beside two more and The Latest rail | The newest featured story |
| Most read | The dark ranked list (up to 5) | The slugs in home.mostRead.stories |
| The Big Story | The full-width photo feature | The slug in home.bigStory.story, then the second featured story |
| Editors’ Picks | The first leads the band; the next four sit below it | The slugs in home.picks.stories |
Band headings stay in src/config/pages.ts. Across Blakey and Analysis and opinion fill themselves.
About
The About document edits /about/ without touching code. Blank fields fall back to pages.about in src/config/pages.ts.
| Tab | What you can change |
|---|---|
| Content | Page title (breadcrumb), eyebrow, heading, subheading, lead image with alt and caption, story (rich text) |
| Masthead | Heading and the name / role list beside the story |
| Standards | Heading and the numbered items at /about/#standards |
SEO for the page is under Site settings → Pages. The reporters grid at the bottom still comes from Reporters.
Site settings
Site settings holds everything site-wide that an editor might change, so nobody has to open the code for it. Any field left blank uses the value in src/config/.
| Tab | What you can change |
|---|---|
| General | Tagline, newsroom email, phone, and address. The email shows on the contact page and in the footer, and the mailto tips form sends to it |
| Header | The top bar’s strapline and links, the section row, and the masthead button |
| Banner | The announcement bar above the masthead: show or hide, message, bold phrases, button, whether it can be closed, and how many days until it shows again to someone who closed it |
| Footer | Tagline, link columns (or a column that lists your sections), legal links, and the copyright line |
| SEO | The home page title and description (also the defaults for other pages), the default social image, your X handle, profile links (shown as footer icons), and keywords |
| Pages | Title, description, and social image for the latest, archive, reporters, about, contact, and newsletter pages. Blank fields use the copy in src/config/pages.ts |
| AI & search | A summary and topics for llms.txt and structured data, questions and answers, notes for AI assistants, and a switch for AI crawlers |
| Analytics | A Google tag (Analytics or Tag Manager) or a Plausible domain, and verification codes for Google Search Console and Bing Webmaster Tools |
- Changing the banner message, bold phrases, or button shows it again to visitors who closed it, so a new announcement reaches everyone.
- Section links fill themselves in. An All sections item in the section row, and List sections on a footer column, add a link for every section. Add a section in the Studio and it appears in both after the next build.
- Questions and answers show as Common questions on the contact page, and that page adds them as FAQ structured data. Search engines only accept FAQ data for questions visitors can see, so they aren’t added anywhere else.
- Allow AI crawlers off asks AI training crawlers (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, and others) to stay away in
robots.txt. Search engines are unaffected. - Analytics only load when the site is served from the domain in
identity.url, so local builds and preview deploys aren’t counted. - Verification: in Search Console or Bing Webmaster Tools, pick the HTML tag method and paste either the code or the whole tag.
The site name, URL, fonts, colors, the banner’s colors, the newsletter provider, and the contact form provider stay in code. See Configuration.
Hosting the Studio
cd studio && npm run deploy
This hosts the Studio at <name>.sanity.studio, so your reporters and editors can write from anywhere. Invite them at sanity.io/manage under your project’s Members. They need to log in; the Studio isn’t public.
Publishing changes
Because the site is static, published changes go live when it rebuilds. A Sanity webhook starts that build every time you publish. The rebuild also refreshes the search index.
If your host builds from Git (Cloudflare Pages, Netlify, or Vercel connected to your repo):
-
In the host’s environment variables, set
PUBLIC_SANITY_PROJECT_IDandPUBLIC_SANITY_DATASETto the values in your.env. -
Create a deploy hook. On Cloudflare Pages it’s under Settings, Builds, Deploy hooks; on Netlify, Build hooks; on Vercel, Git, Deploy Hooks.
-
Add it to
studio/.env:DEPLOY_HOOK_URL=https://... -
Run
cd studio && npm run webhook.
If you build with GitHub Actions:
-
Add
PUBLIC_SANITY_PROJECT_IDandPUBLIC_SANITY_DATASETas repository variables (not secrets) under Settings, Secrets and variables, Actions. -
Create a fine-grained GitHub token with Contents: read and write on the repository.
-
Add to
studio/.env:GITHUB_REPO=owner/repo GITHUB_DISPATCH_TOKEN=github_pat_... -
Run
cd studio && npm run webhook. The workflow needs arepository_dispatchtrigger of typesanity-publish; the included.github/workflows/deploy-pages.ymlhas one.
The webhook fires when a story, section, reporter, the front page, or Site settings is published, changed, or deleted. Publish a small change and check that your host starts a build.
Previewing drafts
The local dev server can show unpublished drafts. At sanity.io/manage, open your project, go to API, Tokens, and create a token with Viewer permissions. Add it to .env:
SANITY_API_READ_TOKEN=...
Builds ignore it and always use published content. Keep it in your local .env only, never in your host’s settings or the repo.
Moving from the Astro edition
If you started with the Astro edition, the Studio can import that site:
cd studio
FROM=../../my-blakey-site DRY_RUN=1 npm run import-markdown # lists what would be imported
FROM=../../my-blakey-site npm run import-markdown
It brings over your sections, reporters, stories with their images, the front page picks, and the masthead, navigation, footer, SEO, and AI settings. Stories marked draft: true arrive as drafts. Running it again updates the same documents instead of duplicating them.
Before launch
On top of the launch steps for every theme:
- Replace or delete the demo stories, sections, and reporters in the Studio, and pick your own stories in Front page. The demo images are AI-generated.
- Fill in Site settings: your newsroom email, masthead links, profile links and X handle, SEO, the AI summary, and the demo questions and answers. Add your Search Console and Bing verification codes, then submit the sitemap in both.
- Set the project ID and dataset on your host, create the publish webhook, and check that a test publish rebuilds the site.
- Deploy the Studio and invite your newsroom.
- Set a newsletter provider in
newsletter.actioninsrc/config/integrations.ts, or remove the sign-up forms. - Remove the demo-only framing header and deploy workflow. See Demo-only settings.