Content Frontmatter: Fields and SEO Metadata

Frontmatter is the page element readers never see as one block and every publishing system depends on. It gives a document an identity, rendering contract, search preview, ownership record, dates, and schema inputs. Broken frontmatter can select the wrong template, create canonical conflicts, lose the author, or emit markup that contradicts the page.

The live specimen is a document-level record, shown as code because frontmatter must not become a decorative body box.

+++
entity = "guide-how-to"
id = "reset-api-key"
title = "How to Reset an API Key"
seoTitle = "How to Reset an API Key Safely"
description = "Reset an API key safely, replace it in every dependent service, verify the new credential, and revoke the exposed key without avoidable downtime."
url = "/academy/reset-an-api-key/"
image = "/images/academy/reset-api-key.png"
imageAlt = "API key settings with the Rotate key action highlighted"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "reset API key", "rotate API key", "revoke API key" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/reset-an-api-key/"

[[faq]]
question = "Does rotating an API key revoke the old key immediately?"
answer = "Not necessarily. Confirm the provider's rotation behavior before changing dependent services."
+++

Why frontmatter exists

For a reader, metadata reduces uncertainty. A precise title sets scope, a useful description earns the click, identities make claims accountable, and dates reveal whether information may have aged. These signals cannot compensate for weak content, but their absence forces the reader to guess.

For machines, frontmatter replaces inference with named values. Templates map fields to browser titles, canonical links, person records, dates, feeds, indexes, and JSON-LD without scraping prose. This is machine extractability: important facts have a consistent location and type.

Follow the element writing rules : metadata belongs at document level; reader-facing elements belong in the body. A byline may render from frontmatter, but its authoritative identifier remains there.

When to use it — and when not to

Every indexable page needs one frontmatter record for identity, rendering, and routing. Drafts need it when they enter production so validation can fail early.

Do not hide article facts in frontmatter. Product limitations, safety warnings, affiliate disclosures, methods, and sources must remain visible where readers can evaluate them. A structured value never substitutes for disclosure.

Near misses cause the most damage:

• Independently varying navigation labels, campaign copy, and social captions are channel settings; do not overload title.
• Organization facts shared across the whole site belong in the site’s organization record, not copied into every page where they will drift.
• A question-and-answer section belongs in [[faq]] only when the same content renders visibly. Hidden schema-only FAQ is invalid.
• A topic label belongs in taxonomy; it must not replace the entity that identifies the document’s post type.
• A redirect belongs in routing configuration or an approved aliases field. canonical identifies the preferred version; it does not redirect visitors.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Frontmatter begins at the first byte with +++ and ends at the matching fence before the body. No heading, comment, note, shortcode, or metadata block may precede it. TOML fields and arrays belong inside that one record.

The body begins after the closing fence. Frontmatter cannot sit between the H1 and introduction, beside a screenshot, inside a component, or at the end. A byte-order mark or stray comment can prevent recognition. Duplicate keys, YAML fences, and second blocks are invalid.

Anatomy

The rendered legend stays in the page so it remains readable and translatable independently of the image:

1. Boundary: the opening and closing +++ fences define the only metadata region.
2. Identity: entity, id, type, and url tell systems what the document is and where it lives.
3. Discovery: title, seoTitle, description, image, imageAlt, and keywords support previews and retrieval.
4. Provenance: date, updated, author, and reviewedBy state who is accountable and when the work was validly changed.
5. Classification: taxonomy joins the page to controlled topic collections without redefining its identity.
6. Duplication control: canonical names the preferred public URL when equivalent versions can be reached elsewhere.
7. Structured collections: each [[faq]] creates one typed question-and-answer record for visible rendering and schema.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Frontmatter has data-contract variants, not visual styles. Screenshots pair source records with their resulting preview or byline.

Parameters

These are editorial limits even when a parser accepts more. “Conditional” means required when its stated condition is true.

Per-field reference

This reference defines the publishing contract for each field. “Required” means validation should stop publication when the field or its valid derivation is absent. “Conditional” means the requirement is activated by a stated fact, such as an image being rendered or an independent review having taken place. A default is safe only when it produces the same meaning an editor would have chosen deliberately.

Identity and routing

title, h1, and seoTitle

• Purpose — title gives the document its durable editorial name. h1 controls the main on-page heading when the layout context needs different wording. seoTitle controls the browser/search title when the default needs a concise qualifier or brand treatment. Separating them prevents a navigation label, page heading, and search preview from being forced into one awkward string.
• Type and format — Each is a plain-text string. title is the source value; absent overrides must fall back to it. HTML, Markdown, emoji decoration, and manual truncation marks are not valid values.
• Required? — title is required on every public page. h1 and seoTitle are optional and should be omitted when title works in all three contexts.
• Limits — Use 30–70 characters for title, 20–80 for h1, and 30–60 for seoTitle as editorial bands, not promises that a search interface will display every character. There must be one rendered H1.
• Who or what consumes it — Page templates, browser titles, search and social adapters, navigation cards, feeds, schema headline, accessibility outlines, and editorial listings.
• Rules — All versions must identify the same subject, intent, and scope. A legitimate difference solves a channel constraint: for example, the H1 may say “How to Rotate an API Key Without Downtime,” while the shorter SEO title says “API Key Rotation: Safe Step-by-Step Guide.” The later Title, H1, and SEO title section explains the editorial test.
• Common mistakes — Repeating a keyword in all three variants, putting a brand suffix into the H1, changing the promise to chase clicks, embedding the current year when the page is not maintained yearly, or authoring three values merely because three fields exist.

slug and url

• Purpose — The slug is the final path segment; url is the site-relative public route that contains it. Together they give the page a stable address for readers, crawlers, links, reporting, and migrations. Stability matters because every earned link and saved bookmark becomes dependent on that address.
• Type and format — Use a lowercase, hyphen-separated path string such as /academy/rotate-an-api-key/. This repository records the complete route in url; a CMS that has a separate slug field must derive the same final segment.
• Required? — A unique route is required for every public page. It may be generated only where a section has an approved deterministic rule and collision checks; playbook pages use their registered url values.
• Limits — Prefer a short, legible slug that preserves the distinguishing subject, usually three to eight useful words. Remove punctuation and empty modifiers. Remove stop words such as “the” or “a” only when the result remains natural and unambiguous; there is no arbitrary character limit that justifies damaging meaning.
• Who or what consumes it — Hugo routing, internal links, breadcrumbs, canonical generation, sitemaps, feeds, analytics, redirects, and external references.
• Rules — Treat a published slug as a permanent commitment. Decide it from the durable topic, not a campaign headline or transient year. When the title changes but the topic and intent do not, keep the old slug. If the page truly moves, create the new route, retain the old route in aliases, update internal links, and test the redirect destination.
• Common mistakes — Regenerating the slug whenever the title changes, stuffing synonyms into the path, retaining dates that make evergreen content look obsolete, using mixed case or underscores, creating two URLs that differ only by a trailing slash, and changing a route without preserving the old one.

canonical

• Purpose — A canonical identifies the preferred URL among equivalent or near-equivalent accessible versions. It consolidates identity; it does not move a visitor or excuse uncontrolled duplication.
• Type and format — One absolute HTTPS URL, including the intended host and normalized path: https://amicited.com/academy/rotate-an-api-key/. The template may derive a self-reference from the page permalink when the site has one trustworthy host and route policy.
• Required? — Every indexable page must emit one canonical. The field itself is conditional when a correct self-referencing value is derived automatically; set it explicitly for an approved cross-domain or exceptional canonical.
• Limits — Exactly one canonical target. The target must return a successful indexable document, use the preferred protocol and host, and represent substantially the same content.
• Who or what consumes it — The HTML <link rel="canonical">, search engines, sitemap and internal-link checks, deduplication reports, and schema URL identifiers.
• Rules — Self-reference by default. Use a cross-domain canonical only when another publisher owns the preferred equivalent and both parties intend consolidation. Use a redirect, not a canonical, when the old URL has been replaced and users should always land on the new one. Keep canonical, sitemap URL, hreflang, internal links, and schema identity aligned.
• Common mistakes — Pointing every paginated or localized page to a generic parent, canonicalizing distinct content, targeting a redirect or error page, mixing HTTP and HTTPS, using the field as a substitute for an alias, and assuming canonical directives are guaranteed to be obeyed.

aliases

• Purpose — aliases preserves routes that previously identified the same page, so a move does not turn existing links and bookmarks into dead ends. It records route history rather than creating alternative indexable identities.
• Type and format — A TOML array of site-relative paths, for example aliases = [ "/blog/old-api-key-guide/" ]. Each value includes a leading and trailing slash and must be unique across the site.
• Required? — Optional for a new page; required whenever a published page moves from a path the site controlled.
• Limits — Include every known former first-party route that still receives links or traffic. Do not add speculative spelling variants or an unbounded list of keyword URLs.
• Who or what consumes it — Hugo’s alias output, deployment redirect processing where configured, migration QA, link monitors, and users following old URLs. Because Hugo can emit an alias page rather than an origin-level HTTP redirect, deployment behavior must be verified instead of assumed.
• Rules — A moved page keeps its old path working. Every alias must resolve in one hop to the current canonical route. Update internal links to the new URL even when the alias works, and preserve the alias across later edits unless a documented redirect system supersedes it.
• Common mistakes — Deleting the old page without an alias, chaining old path to intermediate path to current path, treating aliases as duplicate publishing routes, pointing several unrelated pages to one convenient destination, or assuming local Hugo output proves the production HTTP status.

type and layout

• Purpose — These fields select the rendering contract. type places a page in a content class with shared templates and behavior; layout requests a specific template within that class. Correct selection ensures the page receives the intended navigation, content slot, assets, and schema behavior.
• Type and format — Lowercase registered strings. This page uses type = "academy". A layout value is a template basename such as single, without a file extension or path traversal.
• Required? — type is required when the content location does not safely imply the intended type or when the playbook contract mandates it. layout is optional and should be omitted when the type’s default template is correct.
• Limits — One value for each field, chosen only from templates maintained by the site. A new value is an engineering change, not an editorial improvisation.
• Who or what consumes it — Hugo’s lookup order, templates, partial selection, CSS and JavaScript inclusion, schema adapters, and validation rules.
• Rules — Choose the post type and rendering contract before drafting. Use layout only for a genuine supported variant; do not use it to compensate for content that belongs to another type. Verify that an override exists and accepts the page’s frontmatter shape.
• Common mistakes — Confusing the editorial entity with Hugo type, naming a template file that does not exist, copying a landing-page type onto an academy document, relying on folder inference during a migration, and introducing one-off layout names that bypass shared improvements.

Discovery

description

• Purpose — The description helps a qualified searcher or sharing recipient decide whether this page answers the need. It is preview copy, not a compressed introduction and not a place to prove relevance through repetition.
• Type and format — One plain-text sentence. It should name the primary term naturally, state the concrete value, and add useful scope, audience, method, or outcome.
• Required? — Required for every indexable page in this playbook.
• Limits — 150–160 characters, including spaces. This is an editorial consistency band, not a display guarantee: search engines may truncate it or rewrite the snippet from body content when another passage better fits the query.
• Who or what consumes it — Meta description tags, Open Graph and Twitter description defaults, listing cards, feeds, CMS previews, search quality checks, and sometimes schema description.
• Rules — Write for a click from the right reader. Make the sentence specific enough to distinguish the page from another result with a similar title. The Description rules section below gives the rationale and rejection tests.
• Common mistakes — Duplicating the title, listing keywords, opening with “Learn everything about,” making an unsupported best-or-fastest claim, using a vague call to action, exceeding the band through an unseen brand suffix, or assuming the authored text must appear verbatim in search results.

keywords

• Purpose — In this repository, keywords records the compact query and terminology set used for editorial QA, corpus search, coverage analysis, and internal tooling. It helps editors recognize the language a page must use accurately; it is not a promise to include every phrase mechanically.
• Type and format — An array of natural-language strings, ordered from the primary term through meaningful variants and closely related terminology.
• Required? — Required under this playbook, including for pages whose public templates do not render the values.
• Limits — Six to eight distinct entries. Each entry must represent a real query phrase or necessary term, not a token-level variation.
• Who or what consumes it — Editorial validators, content inventories, search and opportunity analysis, internal retrieval, and migration tools. Public search engines do not use this field as a ranking signal merely because it exists.
• Rules — Keep the set focused on one page’s scope. Merge case, punctuation, singular/plural, and trivial word-order duplicates. Use the phrases to check coverage and terminology, never to dictate unnatural density.
• Common mistakes — Treating the field as the obsolete meta-keywords ranking mechanism, adding dozens of variants, repeating the title as eight near-duplicates, inserting competitor names the body does not discuss, and allowing the array to replace proper taxonomy or prompt targets.

targetPrompts

• Purpose — targetPrompts records the complete questions or requests that a person may give an AI answer system and for which this page should be a useful source. Prompt targets preserve conversational context that short keyword phrases omit.
• Type and format — An array of complete, natural-language strings, for example targetPrompts = [ "How do I rotate an API key without downtime?", "What should I check before revoking an old API key?" ]. Keep wording as a user would ask it, including audience, constraints, or desired comparison.
• Required? — Conditional for pages included in prompt tracking or an AI-visibility content program; optional when no tracked prompt set exists.
• Limits — Use a small, intentional set, normally one primary prompt and up to four meaningful variants. A prompt may be longer than a keyword because its qualifiers carry intent.
• Who or what consumes it — Content briefs, prompt-tracking workflows, retrieval and coverage audits, AI-answer monitoring, and editorial evaluation. It is not rendered as hidden search copy.
• Rules — Separate prompts by actual information need, not punctuation. A keyword such as “API key rotation” names a topic; “How can a SaaS team rotate an API key without interrupting integrations?” names an audience, task, and constraint. The page must answer every stored prompt honestly.
• Common mistakes — Copying the keywords array into this field, fabricating dozens of syntactic variations, recording prompts broader than the page, using prompts as body headings regardless of reading flow, and claiming prompt coverage when the answer depends on information the page does not provide.

Trust and provenance

date and updated

• Purpose — date preserves when the page was first published; updated reports the latest substantive change or completed review. Two fields preserve history while showing whether information readers rely on has changed.
• Type and format — Timestamp strings in the site convention, YYYY-MM-DD HH:MM:SS. Keep one timezone policy across the corpus so feeds and comparisons remain deterministic.
• Required? — date is required for published editorial pages. updated is optional until a qualifying change occurs, then required if the page presents a modified date.
• Limits — One value each. updated cannot precede date or lie in the future. A correction made minutes after publication may still be documented, but routine draft revisions before publication do not create an updated date.
• Who or what consumes it — Visible bylines and freshness stamps, feeds, sitemaps, schema datePublished and dateModified, recency audits, sorting, and editorial queues.
• Rules — Reset updated for a factual correction, changed instruction, new or removed evidence, revised scope, materially changed recommendation, or a documented review of time-sensitive claims. Never reset it for punctuation, formatting, template work, or a timestamp-only edit. See Dates, authors, and reviewers for the policy rationale.
• Common mistakes — Overwriting the original date during a refresh, future-dating a page to appear fresh, bumping dates without a content diff, treating an automated deploy as an editorial update, and failing to record what changed in the maintained update history.

author

• Purpose — author connects the document to the accountable person entity responsible for its work. The link gives a reader and a machine a path from a claim-bearing page to maintained identity, expertise, and other work.
• Type and format — A stable author identifier that resolves through the site’s author registry to a profile URL and Person record. For example, author = "maya-chen" is valid only if that identifier resolves; a display name such as "Maya Chen, SEO Expert" is not a substitute for the entity link.
• Required? — Required for substantive editorial pages. Transactional pages may use a governed organizational owner only when the template and policy support that entity type.
• Limits — One accountable lead by default; use a documented identifier array only when the schema and byline templates support genuine co-authorship.
• Who or what consumes it — Visible bylines, author profile links, Article schema, feeds, editorial ownership reports, review workflows, and entity graphs.
• Rules — Resolve the identifier before publication. The profile must identify the same person shown in the byline and stay maintained. Credit the person who is accountable for the content, not the person who merely uploaded it.
• Common mistakes — Entering an unlinked name string, using “Admin” or an invented editorial team, assigning a prominent executive who did not author the work, allowing an identifier to resolve to no profile, and changing authorship to imply expertise that was not involved.

reviewedBy, reviewedAt, and reviewScope

• Purpose — These fields record an independent review distinct from authorship. reviewedBy identifies the reviewer entity; reviewedAt states when the review was completed; reviewScope says what the reviewer checked, so the badge does not imply approval beyond the evidence.
• Type and format — reviewedBy is a stable identifier resolving to a maintained person profile. reviewedAt uses the site timestamp format. reviewScope is a concise plain-text statement such as “Credential rotation steps and security cautions.”
• Required? — Conditional when law, risk policy, subject sensitivity, or the post-type specification requires independent review. When reviewedBy is present, review date and scope are required as review-record data, even if a particular template stores them in a connected editorial record rather than public frontmatter.
• Limits — Name only actual reviewers. Scope should be specific enough to reveal exclusions without becoming a review report. A reviewer must have relevant competence and must not simply duplicate the author role.
• Who or what consumes it — Reviewed-by components, person entity joins, governance audits, high-risk publication gates, structured provenance, and update logs.
• Rules — Complete review after the content is stable, capture findings and resolution in editorial history, and re-review when later changes affect the reviewed scope. Independent means the reviewer tests the work rather than endorsing their own draft.
• Common mistakes — Treating copyediting as expert review, displaying a reviewer with no date or scope, naming someone who never saw the final version, leaving the badge after a material unreviewed rewrite, and implying legal, medical, or technical approval outside the stated scope.

Media and social

image and imageAlt

• Purpose — image selects the representative hero and social asset; imageAlt supplies the functional text alternative when that asset is rendered as meaningful page content. Keeping the pair together prevents discovery imagery from becoming an accessibility omission.
• Type and format — image is a resolvable site path or approved absolute URL. imageAlt is plain text describing the image’s useful information in its page context, not its filename or target keyword.
• Required? — Conditional by post type and template. If the page requires a hero or dedicated social image, image is required. imageAlt is required whenever that image renders informatively; a purely decorative rendering must use an empty alt attribute in the template, not invented descriptive text.
• Limits — Use one representative asset. For social compatibility, provide a 1200 × 630 pixel source in the expected crop ratio, keep important content away from edges, and keep imageAlt concise—normally 5–160 characters. The file must exist before it is referenced.
• Who or what consumes it — Hero components, listing cards, Open Graph and Twitter tags, schema image fields, feeds, image pipelines, screen readers when visible, and asset QA.
• Rules — Choose an image that still communicates after a center crop and at thumbnail size. Describe its function in context: “API key settings with Rotate key highlighted” is useful; “API key” is not. Do not put essential claims only inside pixels.
• Common mistakes — Referencing a planned asset that does not exist, using a logo as every article image, embedding small text that becomes illegible in shares, writing “image of,” stuffing keywords into alt text, and assuming social alt text and visible-image alt behavior are identical across platforms.

Open Graph and Twitter card fields

• Purpose — Social metadata controls how a URL is summarized when shared. A consistent title, description, URL, type, and image help recipients recognize the page before clicking and reduce the chance that a platform selects an irrelevant asset.
• Type and format — In this repository, templates derive og:title and twitter:title from title, descriptions from description, URLs from the permalink, og:type from the layout context, and both image tags from image with a site fallback. twitter:card is emitted as summary_large_image. These are generated tags, not duplicate frontmatter fields by default.
• Required? — The output tags are required on public pages. Separate overrides are optional and should be introduced only through a documented template contract; unsupported ad hoc fields such as ogTitle do nothing.
• Limits — One coherent preview per page and one 1200 × 630 representative image. Keep derived wording within the title and description bands, then test the actual crop and overlay behavior on major sharing surfaces.
• Who or what consumes it — Social networks, messaging clients, link unfurlers, browser extensions, collaboration tools, and share-preview debuggers.
• Rules — Prefer derivation so search and social claims stay aligned. Override only when the social context genuinely needs different framing and the template supports it. A wrong image costs recognition and trust: the recipient may see an obsolete interface, another product, a misleading claim, or a crop that hides the subject.
• Common mistakes — Authoring fields that no template reads, allowing a global fallback to mask a missing required hero, using a portrait or tiny image for a wide card, changing social copy to make a stronger promise than the page, and validating only the HTML source rather than a fetched preview.

Classification

taxonomy, categories, and tags

• Purpose — Classification connects a page to governed topic, format, audience, or product collections. It powers useful archives and filters only when each vocabulary has a declared meaning; otherwise labels become an uncontrolled synonym pile.
• Type and format — Arrays of registered lowercase slugs. Use taxonomy for the repository’s controlled topic vocabulary. Use categories only for a small mutually intelligible editorial hierarchy and tags only for a governed cross-cutting vocabulary when those taxonomies are configured.
• Required? — Conditional on the post type and archive design. Topic-bearing editorial pages normally require one or more controlled terms; utility pages may require none. A field must not be populated merely because a CMS exposes it.
• Limits — For general taxonomy, one to five values per controlled vocabulary. Each term needs a definition, owner, and merge rule. Create an indexable archive only when the term represents durable reader demand and the archive can offer a unique introduction, coherent inventory, internal links, and ongoing maintenance.
• Who or what consumes it — Archive pages, breadcrumbs, filters, related-content systems, faceted navigation, content audits, and analytics segmentation.
• Rules — Choose the narrowest registered term that accurately groups the page. Keep singular/plural, abbreviations, and spelling variants mapped to one canonical value. Decide whether archives are indexable at the vocabulary level, not tag by tag after accidental creation.
• Common mistakes — Using seo, SEO, search-optimization, and search engine optimization as separate values, adding one-off tags to describe every noun, confusing a business type with a topic, generating thin indexable archives, and deleting terms without migrating their members.

Playbook join keys

• Purpose — playbookPillar, playbookFamily, playbookWave, postTypes, elements, businessTypes, journeyStage, and amicitedFeatures are typed join keys. They let one source page appear in generated libraries and matrices without editors copying cards by hand. This page is the worked example: its pillar identifies an element, its family groups metadata guidance, and its postTypes array declares the specifications that consume it.
• Type and format — Singular keys use registered lowercase slugs: playbookPillar and playbookFamily are strings, playbookWave is an integer, and journeyStage is a controlled string. Relationship keys—postTypes, elements, businessTypes, and amicitedFeatures—are arrays of registered slugs from their respective registries.
• Required? — playbookPillar and playbookWave are required on playbook records. playbookFamily is required where the pillar has governed families. The array joins and journeyStage are conditional: populate only relationships the page contract actually supports.
• Limits — One pillar, one family within that pillar, one wave, and one journey stage unless the model explicitly allows multiple stages. Arrays contain unique registered keys, not display labels, prose, or URLs.
• Who or what consumes it — Playbook hub listings, cross-pillar matrices, filters, relationship cards, completeness reports, release-wave views, and internal tools that find relevant AmICited capabilities.
• Rules — Validate every value against the canonical registry. Direction matters: a post-type page lists its required elements; an element page lists applicable postTypes; a business-type page lists useful post types. Treat labels as presentation and keys as durable data. Rename a key only through a migration that updates every side of the join.
• Common mistakes — Inventing near-synonyms, storing titles instead of slugs, mixing integers and strings for waves, adding a relationship because two pages mention each other, allowing reciprocal arrays to contradict one another, and creating hand-maintained listing markup that drifts from metadata.

Derived and structural fields

schemaType

• Purpose — schemaType selects the most specific supported structured-data mapping that accurately describes the visible page. It tells the schema adapter which vocabulary contract to apply; it does not turn the page into that thing by declaration alone.
• Type and format — One registered Schema.org type name such as Article, selected from the types the site adapter supports. Case and spelling must match the registry.
• Required? — Conditional. Set it where multiple schema mappings are valid for the same Hugo type or where the post-type contract requires an explicit type. Otherwise let the template derive its safe default.
• Limits — One primary page type, with nested entities created by the adapter from actual content. The selected type must satisfy all required properties and match what a reader can see.
• Who or what consumes it — JSON-LD adapters, rich-result validation, content QA, and schema inventory reports.
• Rules — Choose from page function and visible evidence, not from the search feature an editor wants. A how-to page without a complete visible procedure cannot earn accuracy by setting a how-to type. Keep schema URLs, dates, people, and images synchronized with their source fields.
• Common mistakes — Selecting a more specific type without its required content, emitting several conflicting primary types, copying a schema value from an unrelated template, assuming valid syntax guarantees eligibility, and putting claims in JSON-LD that readers cannot inspect.

Reading time

• Purpose — Reading time gives a reader a rough effort estimate. It is derived from the final renderable body so the estimate changes when the actual reading load changes.
• Type and format — A computed integer number of minutes produced from the content pipeline’s word-count policy. Code blocks, tables, captions, and embedded media should follow one documented counting rule.
• Required? — The display is optional by template. An authored frontmatter field is not allowed as the source of truth.
• Limits — Round consistently and apply a sensible minimum display such as one minute. The precise words-per-minute assumption matters less than using the same method throughout the site and labeling the result as an estimate.
• Who or what consumes it — Page headers, cards, feeds, analytics segmentation, and readers deciding whether to start a long guide.
• Rules — Calculate after shortcodes and excluded regions are handled according to the site policy. Recompute on every build. If video or an interactive task materially changes completion time, label that separately rather than corrupting reading time.
• Common mistakes — Authoring readingTime = 8, forgetting to update it after a rewrite, presenting false precision, counting navigation and boilerplate, and treating an execution-heavy how-to as eight minutes of reading plus no task time.

[[faq]]

• Purpose — [[faq]] stores visible question-and-answer pairs once so the page and any eligible FAQ structured data cannot drift apart.
• Type and format — A TOML array of tables; each item contains one plain-text question and one self-contained answer string.
• Required? — Conditional when genuine follow-up questions remain after the main page. It is never required merely to fill a template or pursue a search feature.
• Limits — Normally four to eight useful items on playbook pages. Each question appears once, and every answer must be complete without relying on accordion order.
• Who or what consumes it — Visible FAQ rendering, FAQPage schema where eligible, page navigation, content QA, and answer extraction.
• Rules — This is a cross-reference contract: follow Why FAQ lives in frontmatter and the later FAQ guidance rather than maintaining separate visible and schema copies. Store only questions every reader can access on the page.
• Common mistakes — Hidden schema-only answers, duplicate headings disguised as questions, promotional answers, unsupported claims, stale JSON-LD, and treating search-result eligibility as guaranteed.

[[lnks]]

• Purpose — [[lnks]] records each governed internal link used in the body, pairing its visible anchor with a destination and maintained description. The record makes links inspectable without scraping rendered HTML and supports migration and QA.
• Type and format — A TOML array of tables with text, path, and title. text is the exact visible anchor, path is a site-relative URL with leading and trailing slash, and title is the destination page’s description.
• Required? — Required for each internal body link governed by this content convention. App deep links and external sources follow their own records and are not disguised as [[lnks]] entries.
• Limits — One record per body-link occurrence when the same anchor may point to different destinations; otherwise exact duplicate records should be removed. The destination must exist or be in the approved canonical slug registry for the coordinated release.
• Who or what consumes it — Internal-link validation, content migration, relationship analysis, link-title generation where supported, and editorial review.
• Rules — Match text to the body anchor verbatim, including capitalization and punctuation inside the link. Use the canonical site-relative path. Write title as an accurate destination description, not as instructions for the current page. Update the record and body together.
• Common mistakes — Using a longer text value than the actual anchor, inventing an unregistered slug, omitting a trailing slash, recording a redirecting old path, describing the source instead of the destination, and leaving a record after its body link is removed.

Required versus optional by post type

The matrix applies the contracts above to the twelve post types currently declared by this element. R means required, C means conditional under the field rules, D means required output that may be derived safely, and O means optional. “Identity” includes entity, id, title, type, and the stable route. “Discovery” includes description and keywords; target prompts remain conditional for every row. aliases is always conditional on a move, while authored reading time is never required.

“Conditional reviewer” is not permission to skip review where accuracy or commercial risk demands it. Best-X and alternatives pages require independent review because their recommendations can materially influence a decision and often change as products, prices, and eligibility change. For other rows, the risk policy, not an editor’s available time, activates the requirement. Likewise, a canonical marked D is still required in rendered HTML; only the frontmatter input may be omitted when the template can generate the correct self-reference.

Frontmatter validation

Validation should reject deterministic defects automatically and reserve judgment for questions that depend on meaning, evidence, or professional competence. The split prevents two opposite failures: asking reviewers to catch syntax a parser can catch perfectly, and pretending a character-count rule can decide whether copy is honest.

Run deterministic checks before editorial review so the reviewer sees a coherent record. Then review the rendered HTML, not frontmatter alone: a valid source value is still a production defect if the selected template ignores it, maps it to the wrong tag, hides required provenance, or generates a canonical that disagrees with the public route. Publication is complete only when source, render, and destination behavior agree.

The entity field

entity answers “what exact post type is this document an instance of?” It does not answer “what topic does this page discuss?” That distinction matters because two documents can address the same topic while doing different jobs. A glossary entry defines “diagnosis”; a blog article may report a change in diagnostic guidance. If both use entity = "diagnosis", downstream systems cannot reliably choose the right template, validation rules, analytics group, or migration.

Use the group prefix plus the post-type slug for variants within a family: guide-how-to, guide-ultimate, comparison-a-vs-b, and comparison-alternatives-to-x. Use the bare name for a standalone type: product-page or case-study. Register the identifier once, keep it stable, and never change it because the topic or target query changes. Put topic concepts in taxonomy and query language in keywords.

Title, H1, and SEO title

These values may differ by context but must describe the same page. title is the durable default. h1 is the visible heading and may be more natural in context. seoTitle serves browser and search results and may add a concise differentiator, legitimate year, or brand suffix.

For example, title = "API Key Rotation", h1 = "How to Rotate an API Key Without Downtime", and seoTitle = "API Key Rotation: Safe Step-by-Step Guide" align on one task. “Free Security Tool” as the SEO title would be deceptive because it changes the promise. Do not create differences merely to insert more keywords.

Description rules

The description exists to help a qualified reader decide to click. Keep it within 150–160 characters, include the primary term naturally, state the page’s concrete benefit, and add a meaningful qualifier such as audience, scope, or outcome. Write one fluent sentence, not a keyword list.

The term confirms relevance; repetition adds no value. Do not duplicate the title, use “Learn everything about,” make unsupported superlatives, or end mid-thought. Search systems may still select different visible text for a query.

Dates, authors, and reviewers

date preserves the first publication timestamp. updated records the latest substantive change: a factual correction, new evidence, changed instructions, revised scope, altered recommendation, or complete review that confirms time-sensitive claims. Record what changed in the editorial history when the policy requires it.

Fixing punctuation, changing a button style, rebuilding a template, or touching the timestamp alone does not reset updated. Advancing a date without work behind it is a policy violation because it tells readers and machines that the content was refreshed when it was not. It is misrepresentation, not a growth tactic.

Author and reviewer fields carry accountable identities into bylines and structured data. The author is responsible for the work. Use reviewedBy only when qualified review occurred, and link both identifiers to maintained profiles. The trust foundations page explains how authorship, dates, evidence, and entity clarity support trust without guaranteeing rankings.

Why FAQ lives in frontmatter

An FAQ is visible content and a structured collection. Storing it once in [[faq]] lets the template render the accordion and identical FAQPage JSON-LD, preventing stale hidden schema.

Include genuine follow-up questions visible to every reader. Do not duplicate headings, hide promotions in answers, or mark up undisplayed questions. Valid markup does not guarantee a search feature.

Syntax and code examples

The cross-platform contract maps fields, not a visible component. The following portable envelope is valid only in an interchange file whose importer recognizes metadata directives:

:::frontmatter{entity="guide-how-to" id="reset-api-key" title="How to Reset an API Key"}
description: Reset an API key safely, replace it in dependent services, verify it, and revoke the exposed key without avoidable downtime.
author: maya-chen
:::

It must be normalized into native page metadata during import. It is not valid in the body of a production article. In Hugo, the correct mapping is TOML between +++ fences at byte one, as shown in the live specimen. There is deliberately no {{< frontmatter >}} shortcode: a shortcode would run too late and in the wrong document region.

In WordPress, map the same canonical fields to registered post fields and post meta, for example post_title, post_excerpt, post_name, _amicited_entity, _amicited_author, and _amicited_reviewed_by. A comment such as <!-- wp:amicited/frontmatter --> or a [frontmatter] shortcode is invalid because it creates a body block rather than document metadata. Importers and editors may present a metadata panel, but the stored values must remain attached to the post record.

Examples

Good: one coherent, accountable record

entity = "guide-how-to"
id = "rotate-api-key"
title = "How to Rotate an API Key"
description = "Rotate an API key safely, update every dependent service, verify the replacement, and revoke the old credential without avoidable downtime."
url = "/academy/rotate-an-api-key/"
date = "2026-08-27 10:00:00"
updated = "2026-09-03 14:30:00"
author = "maya-chen"
reviewedBy = "alex-rivera"
keywords = [ "rotate API key", "API key rotation", "revoke API key", "credential security", "API security", "secret rotation" ]
taxonomy = [ "security", "account-administration" ]
canonical = "https://amicited.com/academy/rotate-an-api-key/"

This identifies a how-to variant, preserves history, names accountable people, and separates topic from page identity. The updated timestamp is supported by a documented instruction change and review.

Bad: the title repeated as a description

title = "How to Rotate an API Key"
description = "How to Rotate an API Key"

The description adds no benefit, scope, or reason to click. It also wastes the preview space that could distinguish this page from every other result using the same title.

Bad: one entity reused across two post types

# glossary entry
entity = "diagnosis"

# editorial guide
entity = "diagnosis"

The shared topic has replaced post-type identity. Use registered values such as glossary-term and guide-ultimate, then assign “diagnosis” through taxonomy or keywords.

Bad: an updated date with no content diff

date = "2026-01-15 09:00:00"
updated = "2026-08-27 10:00:00" # only the date changed

No substantive edit or review supports the freshness claim. Keep updated unchanged or omitted until a real change exists and can be inspected in editorial history.

Schema markup and accessibility

Metadata supplies values; the template remains responsible for semantic HTML, focus, contrast, link purpose, and alternative text.

Writing rules

• Keep identifiers stable, lowercase, and machine-safe. Never recycle an id or silently change entity after publication.
• Use plain text in title-like fields. HTML, Markdown links, emoji decoration, and forced line breaks do not belong in metadata strings.
• Keep the description at 150–160 characters and keyword arrays at six to eight distinct phrases for this playbook.
• Use real registered people for author and reviewer fields. Never create a ceremonial reviewer or generic “Editorial Team” identity unless that is a maintained accountable entity.
• Use a controlled taxonomy. Spelling variants and singular/plural duplicates create fragmented archives.
• Reference only images that exist and have publication rights. imageAlt describes the image’s informative content, not its SEO target.
• Keep FAQ answers direct and self-contained. Claims still require the same evidence and disclosure as prose elsewhere on the page.
• Never place secrets, private notes, access tokens, embargo instructions, personal data, or unreviewed legal claims in publishable frontmatter.

Which post types use frontmatter, and where

Every post type uses frontmatter at byte one. The required depth changes with risk, intent, and schema rather than with visual design.

QA checklist

• Does the file start with +++, contain valid TOML, and close the record before body content?
• Is entity a registered exact post-type identifier rather than the topic, campaign, or site name?
• Is id unique and stable, and does url match the canonical slug registry?
• Do title, optional h1, and optional seoTitle describe the same page without deceptive scope changes?
• Is the description 150–160 characters, does it contain the primary term naturally, and does it offer a concrete reason to click?
• Does every referenced image exist, and is imageAlt accurate for the image that renders?
• Is the publication date preserved, and is every updated value supported by a substantive diff or documented review?
• Do author and reviewer identifiers resolve to real maintained profiles, and did the named reviewer actually review the work?
• Are keywords limited to six to eight useful phrases and taxonomy values drawn from controlled vocabularies?
• Does the canonical use HTTPS, resolve to the preferred page, and agree with the sitemap and internal links?
• Does every [[faq]] item contain one useful question and self-contained answer that render visibly in identical wording?
• Does generated JSON-LD match visible content, use stable identifiers, and pass syntax validation without claiming unsupported types?
• Are secrets, private editorial notes, unsupported claims, and body-only disclosures absent from the record?

FAQ

Is frontmatter visible on the published page?

The source record is hidden, but templates may render the title, people, dates, and FAQ. Other fields feed previews, canonical tags, feeds, sitemaps, schema, and internal systems.

Should the entity field contain the topic or the post type?

It identifies the exact post type. Shared topics belong in taxonomy and keywords, not in place of document identity.

Can the title, H1, and SEO title be different?

Yes. The H1 may read more naturally and the SEO title may add a differentiator, but all versions must make the same promise.

When should the updated date change?

Change it after a substantive factual review or edit. Do not change it for punctuation, styling, template work, or a date-only refresh.

Why are FAQ questions stored in frontmatter?

The structured array lets one source render both the visible FAQ and matching FAQPage JSON-LD. That prevents schema from drifting away from what readers can inspect.