In the Astro edition, everything lives in the repo: stories and reporters are Markdown files, sections 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 Blakey overview.
Writing a story
Stories go in src/content/news/, one file each. The file name is the URL: night-trains.md becomes /news/night-trains/.
---
title: The night trains are coming back
description: Three new sleeper routes open this spring, and the operators say demand is outrunning the carriages.
date: 2026-11-02
section: business
authors: [maya-okafor, hana-sato]
format: feature
tags: [trains, travel]
image: ../../assets/news/night-train.jpg
imageAlt: A sleeper train waiting at a platform at dusk
imageCaption: The first northbound sleeper leaves at 9:40 p.m.
imageCredit: "Photo: Blakey"
featured: true
---
| Field | Required | Notes |
|---|---|---|
title |
Yes | The headline, 3–120 characters |
description |
Yes | The dek: one or two sentences under the headline, 15–220 characters |
section |
Yes | An id from src/content/sections.json. The build fails if it doesn’t match |
authors |
Yes | One or more reporter ids (file names in src/content/authors/), in byline order |
format |
No | news (default), feature, analysis, explainer, opinion, or review. See Story formats |
image |
No | Path to the lead image, relative to the story file. Put images in src/assets/news/ |
imageAlt |
With image |
Describes the lead image |
imageCaption, imageCredit |
No | Shown under the lead image |
featured |
No | true puts the story in the front page’s lead spots |
progressBar |
No | Shows or hides the reading progress bar on this story, whatever story.progressBar is set to |
date, updatedDate, tags, draft, and seo work as described in Content & blog. Quote any value that contains a colon followed by a space, like the credit above.
Lead images are optimized like every other photo. Use a landscape image at least 1600 pixels wide. The same image becomes the story’s social card and its search thumbnail.
Reporters
Each reporter is a Markdown file in src/content/authors/. The file name is their id and URL (/authors/maya-okafor/):
---
name: Maya Okafor
role: Business reporter
bio: Maya covers work, money, and the companies that shape both.
image: ../../assets/authors/maya-okafor.jpg
location: Chicago
email: maya@example.com
links:
- label: Bluesky
href: https://example.com/maya
order: 3
---
name, role, and bio are required. Use a square portrait. order sets the order on the reporters page; lower numbers come first.
Sections
Sections live in src/content/sections.json:
[
{
"id": "climate",
"title": "Climate",
"description": "Energy, weather, and the work of adapting to a warmer world.",
"order": 3
}
]
idis the URL (/section/climate/) and what stories use insection. Use lowercase words and hyphens.titleanddescriptionappear on the section page and in section lists.ordersets the order in section lists. Lower numbers come first.
The masthead and footer links aren’t automatic. The section row and the footer’s Sections column are written out in src/config/identity.ts, so add, rename, or remove section links there too.
The front page
The newest featured: true story leads. Pick the other bands by slug in src/config/pages.ts:
| Setting | Stories |
|---|---|
home.mostRead.stories |
Five slugs, in rank order |
home.bigStory.story |
One slug. Leave it empty to use the second featured story |
home.picks.stories |
Five slugs: the first leads, the next four sit in a row below it |
A slug is the story’s file name without .md.
SEO and AI
Blakey’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 |
| Latest, archive, reporters, about, contact, and newsletter 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 |
| Google tag or Plausible, Google and Bing verification | analytics and seo.verification in integrations.ts. See Analytics |
| A story’s search title, description, social image, hiding it | The story’s seo frontmatter |
- Questions and answers in
aeo.faqappear on the contact page as Common questions, with FAQ structured data on that page only. /llms.txtlists the publication, sections, reporters, and every story with a link to its Markdown version./llms-full.txthas every story in full.- Hiding a story with
seo.noindex: truealso keeps it out of the sitemap, search,llms.txt,llms-full.txt, and/schema/news.json, and skips its.mdversion.
Before launch
On top of the launch steps for every theme:
- Replace the demo stories, reporters, and sections with your own, and the images in
src/assets/news/,src/assets/authors/, andsrc/assets/images/newsroom.jpg. They’re AI-generated for the demo. - Update the masthead, section row, and footer in
src/config/identity.ts, and the front page picks insrc/config/pages.ts. - Fill in
seoandaeoinsrc/config/integrations.ts, including your real X handle and profile links, then add your search console verification codes. - 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 stories.