Skip to content

Themes / Blakey

Astro edition

Writing Blakey stories as Markdown files, with reporters as Markdown, sections in a JSON file, and images in the repo.

Browse the docs

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: [email protected]
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
  }
]
  • id is the URL (/section/climate/) and what stories use in section. Use lowercase words and hyphens.
  • title and description appear on the section page and in section lists.
  • order sets 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.faq appear on the contact page as Common questions, with FAQ structured data on that page only.
  • /llms.txt lists the publication, sections, reporters, and every story with a link to its Markdown version. /llms-full.txt has every story in full.
  • Hiding a story with seo.noindex: true also keeps it out of the sitemap, search, llms.txt, llms-full.txt, and /schema/news.json, and skips its .md version.

Before launch

On top of the launch steps for every theme:

  1. Replace the demo stories, reporters, and sections with your own, and the images in src/assets/news/, src/assets/authors/, and src/assets/images/newsroom.jpg. They’re AI-generated for the demo.
  2. Update the masthead, section row, and footer in src/config/identity.ts, and the front page picks in src/config/pages.ts.
  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 stories.