Skip to content

Themes / Waldron

Astro + Sanity edition

Running Waldron on your own Sanity project, writing in the Studio, editing site settings, and rebuilding on publish.

Browse the docs

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:

  1. Installs the Studio’s dependencies in studio/.
  2. Logs you in to Sanity if needed. A browser window opens.
  3. Creates a project with a public production dataset, or uses the one already in .env.
  4. Writes the project ID and dataset to .env and studio/.env, keeping anything else in those files.
  5. Imports the demo content: 14 posts, 5 categories, the author, Site settings, and their images.
  6. 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.progressBar in src/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):

  1. In the host’s environment variables, set PUBLIC_SANITY_PROJECT_ID and PUBLIC_SANITY_DATASET to the values in your .env.

  2. Create a deploy hook. On Cloudflare Pages it’s under Settings, Builds, Deploy hooks; on Netlify, Build hooks; on Vercel, Git, Deploy Hooks.

  3. Add it to studio/.env:

    DEPLOY_HOOK_URL=https://...
  4. Run cd studio && npm run webhook.

If you build with GitHub Actions:

  1. Add PUBLIC_SANITY_PROJECT_ID and PUBLIC_SANITY_DATASET as repository variables (not secrets) under Settings, Secrets and variables, Actions.

  2. Create a fine-grained GitHub token with Contents: read and write on the repository.

  3. Add to studio/.env:

    GITHUB_REPO=owner/repo
    GITHUB_DISPATCH_TOKEN=github_pat_...
  4. Run cd studio && npm run webhook. The workflow needs a repository_dispatch trigger of type sanity-publish; the included .github/workflows/deploy-pages.yml has 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:

  1. Replace or delete the demo posts, categories, and author in the Studio. The demo images are AI-generated.
  2. 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.
  3. Set the project ID and dataset on your host, create the publish webhook, and check that a test publish rebuilds the site.
  4. Deploy the Studio and invite your editors.
  5. Remove the demo-only framing header and deploy workflow. See Demo-only settings.