Waldron

Waldron is a blog theme, so everything in the Basics docs applies. This page covers what it adds on top: categories, richer post frontmatter, extra blog pages, and the listing components that build them.

Pages

Page	URL	File
Home	/	src/pages/index.astro
Journal, paginated	/blog/, /blog/2/, …	src/pages/blog/[...page].astro
Category	/blog/category/<id>/	src/pages/blog/category/[category].astro
Archive, grouped by year	/blog/archive/	src/pages/blog/archive.astro
Post	/blog/<slug>/	src/pages/blog/[slug].astro
Component reference	/layouts/	src/pages/layouts.astro

The about, contact, legal, and 404 pages are the standard ones.

/layouts/ shows every listing component with its options, so you can pick a look before editing a page. It’s hidden from search engines and the sitemap. Keep it while you build, then delete the file if you don’t want it on the live site.

Writing a post

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.

Featured posts

The home page leads with your featured posts, newest first:

• The first featured post is the large spotlight at the top.
• The second featured post is the full-width image feature lower down.

With no featured posts, the newest post takes the top spot. Mark two or three posts as featured and update them as you publish.

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.

Page settings

Waldron’s copy is in src/config/pages.ts, as in every theme, with a few extra settings:

Setting	What it does
home.latest, home.categories, home.more	Headings and button labels for the home page sections
home.readingList.posts	The “Start here” list: post slugs (file names without .md), in order
blog.pageSize	Posts per journal page. Default 8
archive	Title, description, and heading for the archive page
post.progressBar	A thin bar along the top of the window that fills as the reader scrolls through a post. Default true; set false to turn it off on every post

The progress bar uses your brand color (--color-brand in theme.css) and is hidden on posts short enough to fit on one screen.

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

Listing components

The post lists are built from components in src/components/posts/. Each one takes its posts as a prop, so you can rearrange pages or change a list’s look without touching how posts are loaded.

Component	Options
PostGrid	columns (2, 3, or 4), image, aspect, variant (plain or bordered), excerpt, category, date, readingTime
PostList	image (left, right, or none), imageSize (sm, md, lg), numbered, dividers, excerpt
PostFeature	One post. layout (split, stacked, overlay), imagePosition, aspect
PostSpotlight	A lead post with a list beside it. sideCount, sideImages
PostArchive	Every post grouped by year. groupByYear, category
CategoryList	variant (cards, pills, list), counts, current
AuthorCard	variant (box, mini, band). Reads the author from identity.ts
Pagination	Page links for the journal

aspect is one of landscape, wide, square, or portrait. For example, to show the home page’s latest posts as a two-column list with small images on the right, change the PostGrid in src/pages/index.astro to:

<PostList posts={latest} image="right" imageSize="sm" />

Adding a CMS

Pages get their posts from loadJournal() in src/lib/posts.ts, which turns Markdown files into simple PostSummary and CategorySummary objects. To use a CMS such as Sanity, fetch your documents there and return the same shapes. The pages and listing components don’t need to change.

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. Remove the demo-only framing header and deploy workflow. See Demo-only settings.