Skip to content

Themes / Waldron

Astro edition

Writing Waldron posts as Markdown files, with categories in a JSON file and images in the repo.

Browse the docs

In the Astro edition, everything lives in the repo: posts are Markdown files, categories are a JSON file, and images sit next to them. There’s nothing to sign up for. For the pages, settings, and components both editions share, see the Waldron overview.

Writing a post

Posts go in src/content/blog/, one file each. The file name is the URL: lisbon.md becomes /blog/lisbon/. Waldron posts need a few more fields than the base theme:

---
title: Three days in Lisbon without a plan
description: No reservations, just a good pair of shoes and a city built on seven hills.
date: 2026-10-28
category: travel
tags: [portugal, walking]
image: ../../assets/posts/lisbon.jpg
imageAlt: A yellow tram climbing a steep cobbled street in Lisbon
featured: true
---
Field Required Notes
category Yes An id from src/content/categories.json, such as travel. The build fails if it doesn’t match a category
image No Path to the cover image, relative to the post file. Put images in src/assets/posts/
imageAlt With image Describes the cover image
featured No true puts the post in the home page’s lead spots
progressBar No true or false shows or hides the reading progress bar on this post, whatever post.progressBar is set to

title, description, date, tags, draft, and seo work as described in Content & blog. Reading time is worked out from the post’s length.

Cover images are optimized like every other photo. Use a landscape image at least 1600 pixels wide. The same image becomes the post’s social card.

Categories

Categories live in src/content/categories.json:

[
  {
    "id": "travel",
    "title": "Travel",
    "description": "Slow trips, good walks, and notes from places worth lingering in.",
    "order": 2
  }
]
  • id is the URL (/blog/category/travel/) and what posts use in category. Use lowercase words and hyphens.
  • title and description appear on the category page and in topic lists.
  • order sets the order in topic lists. Lower numbers come first.

Each category gets its own page automatically. To rename one, change its title. To change its id, update every post that uses it as well.

The menu and footer links aren’t automatic. The Journal dropdown and the footer’s Topics column are written out in src/config/identity.ts, so add, rename, or remove category links there too.

The author

The author’s name, role, and bio come from author in src/config/identity.ts. The portrait is src/assets/images/author.jpg; replace that file with your own photo under the same name.

SEO and AI

Waldron’s search, social, and AI settings are the same as the Astro + Sanity edition’s Site settings, edited in files instead:

Setting Edit in
Default title, description, social image and its alt text, X handle, profile links, keywords seo in src/config/integrations.ts
Journal, archive, about, and contact titles and descriptions title and description under each page in src/config/pages.ts
Summary, topics, questions and answers, notes for AI assistants, AI crawlers aeo in integrations.ts (summary, knowsAbout, faq, llmsNotes, allowAiCrawlers)
Google tag or Plausible, Google and Bing verification analytics and seo.verification in integrations.ts. See Analytics
A post’s search title, description, social image, hiding it The post’s seo frontmatter

How these work in Waldron (see SEO & AEO for the basics every theme shares):

  • Questions and answers in aeo.faq appear on the contact page as Common questions, with FAQ structured data on that page only. Leave the list empty to hide the section.
  • /llms.txt lists the author, topics, pages, Waldron’s categories, and every post with a link to its Markdown version, plus your llmsNotes. /llms-full.txt has every post in full.
  • Turning off allowAiCrawlers blocks nine AI training crawlers in robots.txt, including GPTBot, ClaudeBot, Google-Extended, and PerplexityBot. Search engines are unaffected.
  • Hiding a post from search engines also keeps it out of the sitemap, llms.txt, llms-full.txt, and /schema/blog.json, and skips its .md version:
seo:
  noindex: true
  • A post’s social image is its hero image, cropped to 1200×630, with imageAlt as the alt text. Set seo.ogImage and seo.ogImageAlt to use a different one.

Before launch

On top of the launch steps for every theme:

  1. Replace the demo images in src/assets/posts/ and src/assets/images/author.jpg. They’re AI-generated for the demo.
  2. Replace the sample posts and categories with your own.
  3. Fill in seo and aeo in src/config/integrations.ts, including your real X handle and profile links, then add your search console verification codes.
  4. Remove the demo-only framing header and deploy workflow. See Demo-only settings.

Want to move to Sanity later? The Astro + Sanity edition can import your posts.