ABS Content Frontmatter: The Canonical Shape

An ABS post is a Markdown document with a YAML header. That header is not decoration. It is the structured record Astro reads before rendering the article: the title used on cards and pages, the description used in summaries, the publication date used for sorting, the image used in previews, and the metadata used for filtering and related-content logic.

The repository schema is the executable authority. The canonical shape described here is the house style layered on top of it: fourteen keys that every normal ABS post should carry, six keys reserved for cases that need them, and one stable order that makes files easy to scan and review.

The canonical header

Start new posts with this shape:

---
title: "A clear title no longer than 120 characters"
description: "A useful summary no longer than 200 characters."
type: guide
category: computers
pubDate: 2026-07-14
image: /images/example-post-2026-7-14.png
imageAlt: "A concise description of the meaningful content in the image"
imagePrompt: "A complete regeneration prompt including composition, palette, exclusions, and 16:9 landscape format."
affiliate: false
sources:
  - name: "Source name"
    url: "https://example.com/source"
facts:
  - label: "Difficulty"
    value: "Beginner"
related:
  - another-post-slug
tags:
  - astro
  - publishing
draft: false
---

The required canonical order is:

1. title
2. description
3. type
4. category
5. pubDate
6. image
7. imageAlt
8. imagePrompt
9. affiliate
10. sources
11. facts
12. related
13. tags
14. draft

Keeping the order fixed has practical value. A reviewer can inspect identity first, then classification and date, then artwork, then commercial and evidence metadata, and finally discovery and publication state. Diffs also stay small because tools do not invent their own ordering.

What the fourteen keys mean

title is the display headline and must be at most 120 characters. Quote it, especially when it contains a colon. description is the dek and meta summary; it must be at most 200 characters and should explain the reader benefit rather than repeat the title.

type accepts exactly news, review, guide, or take. Use news for a reported development, review for a first-hand product assessment, guide for instructional or explanatory evergreen material, and take for a clearly argued editorial position. These are lowercase enum values, not free-form labels.

category accepts exactly ai, gadgets, computers, or gaming. Choose the reader-facing subject, not the production method. A guide written with AI about repairing a keyboard belongs in computers, not automatically in ai.

pubDate is an ISO-style calendar date such as 2026-07-14. Use a real publication date and do not split it across lines. image, imageAlt, and imagePrompt work together and are covered below.

affiliate is a boolean. Set it to true only when the post contains monetized affiliate links; that value triggers the disclosure behavior. Otherwise set it explicitly to false.

sources is a list of objects with name and an absolute url. Do not use /about, www.example.com, or a guessed domain. Every URL must include https:// or http:// and must identify the source a reader can visit. An evidence-free original guide may use sources: [], but the key stays present.

facts supplies the compact quick-facts panel. Each item has a label of at most 40 characters and a value of at most 120. Use facts: [] when no panel helps. If a tag, fact value, or other scalar is purely numeric, quote it—for example, - "2026" or value: "95"—so YAML does not silently turn it into a number where the schema expects a string.

related contains post slugs only, without a leading slash, domain, .md, or trailing slash. tags contains short discovery labels, each no longer than 30 characters. Tags are not categories; they can be more specific. draft is the final publication switch and should remain true until the post is ready to ship.

Image path, alt text, and prompt conventions

The image value is a site-root path, normally /images/<slug>-YYYY-M-D.png. It is not a filesystem path such as src/assets/..., not an absolute public URL, and not bare images/.... The leading slash tells the rendered page to resolve it from the public site root. Keep the filename tied to the post slug and actual asset so replacement and cache-busting remain predictable.

imageAlt describes what a reader needs to understand from the finished image. It should describe the visible subject, action, and relevant setting. It should not begin with “image of,” stuff keywords, repeat the headline, or describe invisible artistic intentions. If the image contains no meaningful information, empty alt text can be appropriate—but featured ABS art normally has a meaningful subject.

imagePrompt is not alt text. It is the production recipe retained so the artwork can be regenerated later. Include visual style, composition, subjects, palette, format, and exclusions such as “no text, no logos, no watermarks.” The prompt can mention details that do not belong in accessible alt text, such as halftone texture or lighting. Conversely, alt text must describe the delivered image, not merely copy a prompt whose generated result may differ.

The six optional keys

The schema currently provides six situational fields beyond the canonical fourteen:

• updatedDate: the date of a substantial revision. Do not change pubDate merely to make an old post appear new.
• grade: a review verdict of A, B, C, D, or F. Use it only for reviews.
• author: an explicit byline override when the site-wide default author is wrong.
• score: an integer from 0 through 100 for editorial ranking and display. A numeric score is genuinely numeric; numeric tags must still be quoted.
• weight: one editorial dimension: signal, frame, evidence, context, people, or industry.
• imagePrompt, when absent from legacy or externally supplied content, is technically optional in the executable Astro schema, but ABS canonical authoring treats it as required alongside image and imageAlt so art can be reproduced.

That last distinction matters: Astro’s schema has compatibility defaults and optional fields so older posts can still build, while the canonical authoring contract is stricter for new work. In the same way, schema defaults may allow omitted arrays or booleans, but new ABS posts should write the fourteen canonical keys explicitly.

Place optional fields near the thing they qualify: updatedDate after pubDate; grade, score, and weight after the image block for review or scoring metadata; and author before related. Do not append optional fields randomly after draft.

From Markdown to published HTML

The pipeline has four useful checkpoints.

First, an author or agent writes the .md file under src/content/posts/. The opening --- delimiters separate YAML frontmatter from Markdown body content. At this point YAML syntax matters: indentation defines arrays and objects, colons can change parsing, and unquoted numeric tags become numbers.

Second, Astro’s content loader discovers the file and parses the frontmatter. The posts collection then validates that data with its Zod schema in src/content.config.ts. String limits, enum values, URL format, date coercion, booleans, arrays, and numeric ranges are checked here. Invalid data should fail the build loudly rather than create a malformed page.

Third, Astro renders the Markdown body into HTML and passes the validated frontmatter to page and layout components. Those components use fields such as title, description, image, facts, tags, and affiliate to build the article chrome, metadata, disclosure, and supporting panels. Frontmatter itself is data; it does not appear as a YAML block on the public page.

Fourth, the build emits static HTML and associated assets for deployment. The browser receives ordinary HTML, not the source Markdown and not the Zod schema. A successful parse therefore proves only that the content is structurally valid. Editors must still verify that the image exists, alt text matches it, links resolve, the selected type and category are honest, and the rendered page reads well.

The compact mental model is:

Markdown file
  -> YAML parse
  -> Astro collection load and Zod validation
  -> layout/component rendering
  -> static published HTML

Common failure modes

The most frequent frontmatter mistakes are small but consequential:

• using how-to instead of the valid guide type;
• inventing a category such as software instead of choosing computers;
• supplying relative source URLs;
• writing image: images/file.png without the leading slash;
• copying imagePrompt verbatim into imageAlt;
• including filenames rather than slugs in related;
• leaving numeric tags unquoted;
• exceeding the title, description, fact, or tag limits;
• assuming a schema default is permission to omit canonical metadata;
• setting draft: false before checking the rendered page.

Treat frontmatter as a small API request to the site. The keys are its fields, the enums are its allowed values, Zod is its validator, and the resulting article page is the response. A stable canonical shape makes that request easy for people to inspect and safe for Astro to publish.