Modelling content for answer engines in a headless CMS!

Why the content model is the AEO strategy

Most Answer Engine Optimization advice is a list of habits: open with a direct answer, add an FAQ, cite sources, show the author and the date, mark it up. Habits decay. The third writer forgets the short answer, the FAQ becomes body prose, and the JSON-LD template emits a dateModified nobody updates.

A headless CMS lets you move each habit into the content model. A required field with a maximum length is present on every page by construction, and a front end that derives its structured data, Markdown and llms.txt from those fields can never publish a representation that disagrees with the visible text.

The method in one sentence: one set of fields, many generated representations. What follows is the field list, the constraints, and the Storyblok plumbing Citable uses.

Signals become fields

Every signal described in What is Answer Engine Optimization maps to a field, a constraint and a downstream use.

The short answer is a separate field, not the first paragraph

A first paragraph is subject to every editorial instinct that produces a warm-up sentence. A required textarea with a character limit gets written as an answer. Citable renders it in a data-speakable="short-answer" block and points the Speakable selector at it.

Author and related terms are relations, not strings

A free-text author field cannot produce a stable Person identifier. A relation to an author story gives every guide the same @id, bio and sameAs links. Related glossary terms work the same way: the term's DefinedTerm @id is reused in the guide's about property, so a crawler can connect the definition to every guide that relies on it.

Sources are structured, not a paragraph of links

A source blok has title, url, publisher and published. The URL pattern check stops a bare domain from being saved as a citation, and the four fields are exactly what a CreativeWork citation needs.

Citable's Storyblok schema

Storyblok distinguishes content types (root components that become stories) from nestable components (bloks that live inside a field of another component). Citable has five content types and a set of small nestables, defined once in TypeScript and pushed to the space with the Management API, so the CMS and the front-end types cannot drift apart.

Content types

• guide — title (max 90), subtitle (max 200), short_answer (required, max 420), category and difficulty (single-option), reading_time (number, computed when empty), author (required single story reference), cover (asset), key_takeaways (bloks: takeaway, max 6), body (richtext, required), faq (bloks: faq_item), sources (bloks: source), related_guides and related_terms (multi story references), seo_title (max 70), seo_description (max 160), published_at and updated_at (date).
• glossary_term — term, definition (required, max 320, emitted as DefinedTerm), also_known_as, expanded (richtext), related_terms, related_guides, faq, seo_description.
• author — name, role, bio (required, becomes the Person description), avatar, website, links (bloks: social_link, become sameAs).
• page — title, seo_description, body (bloks: hero, feature_grid, guide_collection, glossary_preview, faq_section, principles, cta, prose_section).
• site_config — site_name, tagline, description, nav, footer_links, ai_policy (published verbatim in llms.txt).

How a relation field is declared

Story references in Storyblok are option (single) or options (multiple) fields with source: "internal_stories". Restricting them by content type and folder turns "a reference" into "an author".

const storyRef = (contentTypes: string[], folder: string, extra = {}) => ({
  type: "option",
  source: "internal_stories",
  use_uuid: true,
  filter_content_type: contentTypes,
  folder_slug: folder,
  ...extra,
});

// in the guide schema
author: storyRef(["author"], "authors/", { required: true }),
short_answer: {
  type: "textarea",
  required: true,
  max_length: 420,
  description: "The direct answer, 40–70 words. This is what answer engines quote.",
},

Rich text with embedded bloks

The guide body is a richtext field. Storyblok stores rich text as JSON nodes (paragraphs, headings, lists, code blocks) rather than HTML, and nestable components can be inserted between them. The @storyblok/richtext documentation puts it plainly: components are embedded as blok nodes, each carrying an attrs.body array that the renderer resolves itself.

Citable uses that for the parts of a guide that need semantics a paragraph cannot carry: callout (variant, title, richtext body), checklist (a list of check_item), stat (value, label, source) and code_block. Because a callout is a component with fields, the Markdown exporter can render it as a blockquote, the plain-text extractor can count its words, and the JSON-LD builder can ignore it. None of them has to parse HTML.

Generating every representation from the same fields

Each machine-readable output is then a pure function of a story.

JSON-LD

Google's Article structured data documentation recommends author, author.name, author.url, datePublished, dateModified, headline and image. All of them are fields or derived from fields. The guide builder returns a TechArticle (a subtype of Article on schema.org) together with Person, FAQPage and BreadcrumbList objects:

const article = {
  "@context": "https://schema.org",
  "@type": "TechArticle",
  headline: c.title,
  description: c.short_answer,
  datePublished: pubDate(guide),
  dateModified: modDate(guide),
  author: { "@id": `${authorUrl}#person` },
  speakable: { "@type": "SpeakableSpecification", cssSelector: ["[data-speakable='short-answer']"] },
  citation: c.sources.map((s) => ({ "@type": "CreativeWork", name: s.title, url: s.url })),
  about: terms.map((t) => ({ "@type": "DefinedTerm", "@id": `${termUrl(t)}#term`, name: t.content.term })),
};

Markdown and content negotiation

The same story renders to Markdown: front matter with the canonical URL, author and both dates, then the short answer, takeaways, body, FAQ and numbered sources. A request for /guides/<slug>.md, or for /guides/<slug> with Accept: text/markdown, is rewritten to that renderer, and the response carries a Link: <…>; rel="canonical" header pointing back at the HTML page.

llms.txt

The index follows the llmstxt.org layout: an H1, a blockquote summary, then sections of - [Title](url): description links. Every description is a guide's short_answer or a term's definition, so the file is a faithful index of the site without anyone maintaining it:

# Citable

> Citable is an open field guide to Answer Engine Optimization (AEO) …

## Guides: Technical

- [Modelling content for answer engines in a headless CMS](https://…/guides/modeling-content-for-answer-engines-in-a-headless-cms.md): A headless CMS content model …

The file's "Policy for AI systems" section is the ai_policy field of site_config.

Wiring Storyblok to the site

Seeding the space with the Management API

Citable's seed script pushes the component definitions and local content into a space. Components are created or updated by name and stories by full_slug, so it is idempotent. Relations need two passes: Storyblok assigns story UUIDs on creation, so the script first creates every story with relation fields emptied, then writes the relations with the assigned UUIDs. Storyblok's Management API documentation states a limit of 3 requests per second on the Starter plan and 6 on higher plans, so the script throttles and retries on 429.

Reading content, published or draft

The front end reads the Content Delivery API with version=published and a resolve_relations list of component.field pairs (guide.author, guide.related_terms and so on), then merges the returned rels array back into each story. Responses are cached with the tag storyblok.

Preview uses Next.js Draft Mode. The Storyblok visual editor loads the site in an iframe from a preview URL set under Settings → Visual Editor; Citable points it at /api/draft?secret=…&slug=, and Storyblok appends its _storyblok parameters. The handler enables Draft Mode and redirects to the story:

import { draftMode } from "next/headers";
import { redirect } from "next/navigation";

export async function GET(request: Request) {
  const url = new URL(request.url);
  if (url.searchParams.get("secret") !== process.env.DRAFT_MODE_SECRET) {
    return new Response("Invalid token", { status: 401 });
  }
  (await draftMode()).enable();
  redirect(`/${url.searchParams.get("slug") ?? ""}`);
}

While Draft Mode is on, the content layer switches to version=draft and cache: "no-store", so editors see unpublished changes immediately.

Webhooks for revalidation

Storyblok's webhook documentation lists published, unpublished, deleted and moved story events, each posting a JSON body with action, full_slug, story_id and space_id. Citable registers one endpoint for publish and unpublish and invalidates everything tagged storyblok:

import { revalidatePath, revalidateTag } from "next/cache";

export async function POST(request: Request) {
  const url = new URL(request.url);
  if (url.searchParams.get("secret") !== process.env.REVALIDATE_SECRET) {
    return Response.json({ ok: false }, { status: 401 });
  }
  const payload = await request.json().catch(() => ({}));
  revalidateTag("storyblok", "max");
  revalidatePath("/", "layout");
  return Response.json({ ok: true, story: payload.full_slug ?? null });
}

Because llms.txt, llms-full.txt, the sitemap, the feed and every Markdown route read through the same tagged fetches, one publish event refreshes all of them. Storyblok's webhook documentation also describes a webhook-signature header that your endpoint can verify against a webhook secret; secrets are only available on paid plans, and that check is stronger than a query-string secret.

Validating content before it ships

Field constraints catch the crude mistakes; a content check catches the ones that need counting. Citable runs a script over every story before it is seeded.

The fixtures the check validates are the ones the seed script pushes, so a guide that passes locally renders correctly in the space. Because the model is data, it can be tested like data.