In the Astro + Sanity edition, posts, categories, the author, and the site settings live in Sanity, and you write 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 Waldron 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: 14 posts, 5 categories, the author, Site settings, and their images.
- Allows the local Studio (
http://localhost:3333) to talk to the project.
| Option | Effect |
|---|---|
--name "My Journal" |
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 |
|---|---|
| Post | Title, slug, description, cover image with alt text, body, category, date, updated date, tags, featured, reading progress bar, and an SEO tab (title, description, social image, hide from search engines) |
| Category | Title, slug (the URL), description, order |
| Author | Name, role, location, bio, photo. There’s one per site, used in bylines, author cards, the about page, and structured data |
| Site settings | Navigation, footer, contact details, SEO, AI and search, analytics. There’s one per site; see Site settings |
- Featured posts lead the home page. See Featured posts.
- Reading progress bar left unset follows
post.progressBarinsrc/config/pages.ts. - The body supports headings, quotes, lists, bold, italic, code, links, and images with captions.
- Lower order numbers come first in topic lists.
Images: after uploading, click Edit and drag the hotspot onto the subject. Cards 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 post adds noindex and also leaves the post out of the sitemap, llms.txt, llms-full.txt, its Markdown version, and the structured data endpoint. It still shows on the site and in RSS.
Category links fill themselves in. The Journal dropdown and the footer’s Topics column list your Sanity categories at build time. Add a category in the Studio and it appears in both after the next build.
To add a field, change the schema in studio/schemaTypes/, then add it to the query and types in src/lib/posts.ts. The repo’s docs/SANITY.md has the details.
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, contact email, phone, and address. The email shows on the contact page and in the footer, and the mailto form sends to it |
| Header | Navigation links, and the button on the right. Turn on Category dropdown for a link to list your categories under it |
| Footer | Tagline, link columns (or a column that lists your categories), 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 journal, archive, about, and contact pages. Blank fields use the copy in src/config/pages.ts |
| AI & search | A summary and topics for llms.txt and structured data, services you offer, 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 |
- 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, 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 you and your editors can write from anywhere. Invite editors 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.
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 post, a category, the author, 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-waldron-site DRY_RUN=1 npm run import-markdown # lists what would be imported
FROM=../../my-waldron-site npm run import-markdown
It brings over your categories, posts with their images, and the author. Posts marked draft: true arrive as drafts. Running it again updates the same documents instead of duplicating them. Your navigation, footer, and SEO settings don’t come over; enter them in Site settings.
Before launch
On top of the launch steps for every theme:
- Replace or delete the demo posts, categories, and author in the Studio. The demo images are AI-generated.
- Fill in Site settings: your contact email, 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 editors.
- Remove the demo-only framing header and deploy workflow. See Demo-only settings.