Content Element Rules: When to Use Each Block

Every page in the SEO playbook depends on one distinction: a piece of content has a purpose, while its heading level and visual appearance are only presentation. These element writing rules turn that distinction into a production contract. Follow them before applying any component, converting an article between publishing systems, or changing an element that already appears on published pages.

Quick overview

• Check the element library by purpose before name. If an element’s purpose matches the job a section performs, that element is mandatory.
• Use plain Markdown only after confirming that no typed element represents the passage’s purpose. Free text is a fallback, not a default.
• Write the complete article as plain text first. Apply elements in a separate top-to-bottom structural pass so composition and markup do not compete for attention.
• Treat the Markdown directive as canonical authored content. Hugo and WordPress renderers map the same fields and body into platform-native output.
• Keep existing published pages on the meaning they were reviewed against. A breaking definition change creates a new version and an explicit migration; it never silently reinterprets old content.

The governing precedence rule

The library must be checked by what a passage does, not by what the writer happened to call it. Names vary: one writer may title a section “What is churn?”, another “Churn explained”, and a third “A working definition”. Their purpose is identical, so all three map to the same definition element.

This precedence exists because free text and a typed element can look identical on screen while behaving completely differently downstream. A styled heading followed by a paragraph may resemble a definition box in the browser, but it carries no component identity. It cannot reliably produce the definition’s structured output, expose its fields to another renderer, retain its semantics during migration, or be found by a quality check that asks whether the page contains a definition. The typed element maps to a component and a known data shape; visually similar free text maps to nothing.

The rule is therefore strict:

Before writing or approving any heading or content block, identify its purpose. If that purpose matches an element definition, use the element. Visual similarity, an existing H2, or the ability to express the same words in a paragraph does not make free text equivalent.

Precedence is semantic rather than visual. A page can still contain ordinary headings inside or around an element when its definition permits them, but the heading never replaces the element type.

Ready to Monitor Your AI Visibility?

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

Get Started Contact

Free text versus a typed element

Use this decision path until the shared diagram is available:

1. State the passage’s job in one verb. Examples include define, warn, summarize, compare, prove, instruct, or invite action. This prevents the heading text from disguising the underlying purpose.
2. Search the library by that purpose and its synonyms. A writer looking only for the literal heading “What is X?” can miss a definition element whose page is named “Definition box”.
3. Use the matching element when one exists. Do not compare appearances or ask whether Markdown could imitate the design; the registered behavior is the deciding factor.
4. Use free text when no purpose matches. This is correct for connective explanation, argument, analysis, narrative context, and transitions that belong to the article’s main flow and require no distinct component behavior.
5. Record a repeated gap. If the same unmatched purpose appears across several pages, propose a library element instead of inventing a one-off directive or CSS treatment in an article.

Plain Markdown is genuinely correct when the words form the article’s continuous reasoning and do not need an independent label, data contract, interaction, or reuse path. For example, two paragraphs explaining why a recommendation follows from the preceding evidence are normal prose. A compact set of conclusions at the top is not normal prose merely because it can be written as bullets; it has the recognized purpose of an overview or takeaways element.

Common confusions that cause incorrect markup

These cases are listed explicitly because they pass a visual review easily. The mistake becomes visible only when another renderer, validator, search index, or structured-output consumer receives the page.

The distinction between key takeaways and a quick overview is especially important. Use takeaways when the items are conclusions the reader should remember, which means they can often be written only after the article exists. Use an overview when the items orient the reader to scope or sequence before reading. Choose by that editorial job, even if the current theme makes both components look alike.

Stay Updated on AI Visibility Trends

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

Email address

Subscribe

Directive and attribute syntax

The canonical Markdown form uses a named block directive. Attributes follow the directive name inside braces:

:::element-name{key=value key2="value with spaces" .class}
Body content
:::

Attributes exist to carry small, stable properties that affect the element’s meaning or supported presentation. Keeping them machine-readable prevents writers from hiding configuration in prose. Use key=value for a value without spaces and key2="value with spaces" when spaces are present. An unquoted attribute value may not contain spaces. A leading dot adds a supported class, as in .compact; it is not a place to invent page-specific styling.

Attribute keys are lowercase and use the exact spelling defined on the element page. Boolean and enumerated values also follow that page’s contract. Do not create an attribute because a renderer happens to tolerate it: an undeclared attribute has no cross-platform guarantee.

Closing ::: fences belong to the outer element. Keep them on their own lines so a parser can distinguish the body from the next paragraph. Code samples that demonstrate directives must stay inside fenced code blocks, as they do on this page, so Hugo does not interpret them as content.

Default body mapping

Most elements need a short title and a longer body. Requiring authors to repeat these as attributes would make long text hard to edit and easy to escape incorrectly, so the body provides the default mapping:

:::example
## A concrete heading

The rest of the body can contain paragraphs, lists, links, and other content allowed by the element definition.
:::

Unless an element page explicitly overrides the rule, the first heading in the body maps to title, and everything after that heading maps to content. The heading marker expresses source hierarchy for editors; the mapped field lets each platform render the appropriate semantic heading level in context.

Only the first body heading receives this special treatment. Later headings remain part of content. If the body has no heading, title is absent; that is valid only when the element definition marks its title optional. If an element defines named slots or a different mapping, its own page takes precedence over this default because the renderer must know exactly where each fragment belongs.

Nested items

Some elements contain a repeatable list whose entries each need attributes and a body, such as steps with identifiers, cards with labels, or checklist items with an initial state. Flattening those entries into one Markdown list would lose their individual fields, so nested items use an explicit item directive:

:::parent-element{variant=compact}
::item{key=value}
### First item title

The first item's explanation.
::
::item{key2="value with spaces"}
### Second item title

The second item's explanation.
::
:::

The contract is ::item{key=value} … ::: two colons open each item, the singular name is item, and two colons close it. The parent keeps its three-colon closing fence. This visual difference matters because it makes nesting unambiguous without relying on indentation, which is easily damaged by copy-and-paste.

Each item applies the same default body mapping unless the parent element page says otherwise: its first heading becomes that item’s title, and the remainder becomes its content. Put attributes on the item when they describe only that item; put them on the parent when they affect the collection as a whole.

Links, images, and inline buttons

Portable source needs predictable paths. A relative URL should be relative to the site root, not to the current Markdown file, because the same source may be rendered at a different filesystem depth in Hugo or imported into WordPress.

• Internal page links use a leading and trailing slash, as the element library link does. Do not use ../, omit the leading slash, or hard-code the production domain for an internal page.
• External links use a complete https:// URL. The scheme is part of the destination and must not be inferred by a renderer.
• Image source files live below cdn-assets/seo-playbook/, and their public paths begin at /cdn-assets/seo-playbook/. Append the approved group and filename only after the asset exists.
• Alternative text describes the information conveyed by an image, not its filename or decorative appearance. A decorative image uses an empty alternative, but the relevant element page must explicitly allow decoration.
• An inline call-to-action uses :button[Visible label]{href="/target/"}. The bracketed text is the accessible label and href follows the same internal or external path rules. Use a button only for a genuine next action, not to make an ordinary reference link more prominent.

An image is content, not a workaround for unsupported layout. If the image contains essential labels, numbers, or instructions, repeat that information in accessible text or use a structured element that exposes it. Screenshot capture requests remain HTML comments until the named asset exists; they are not published image references and must set screenshotsPending = true in frontmatter.

Frontmatter and body elements have different jobs

Frontmatter describes the document as a document. Body directives describe meaningful blocks inside the reading experience. Keeping those layers separate lets listing pages, schemas, routing, and publication tools read metadata without parsing visible prose.

Metadata elements therefore live in frontmatter: page title, description, keywords, publication and update dates, canonical or alias information, ownership, taxonomy, playbook joins, and any schema-oriented collections that the page contract places there, such as FAQ entries on academy pages. These fields are never written as ::: directives. A visible block that repeats some metadata does not move the authoritative field out of frontmatter; it receives its own body element only when it has a separate reader-facing purpose.

Content elements live in the body: definitions, warnings, tips, overviews, takeaways, checklists, comparisons, evidence blocks, examples, steps, and calls to action. They are directives because their location in the narrative matters. Moving a warning into frontmatter would disconnect it from the passage it qualifies; hiding metadata in a body directive would make document-level systems unable to find it reliably.

Metadata is required by default

Metadata drives routes, previews, discovery, joins, and structured output before anyone reads the body. An omitted field can therefore break consumers that never render the article. For that reason, every metadata element is required unless its element page explicitly says it is optional.

Required means populated with a valid value, not merely present as an empty string or empty collection. Do not infer optionality from another page’s omission, and do not add placeholder values to satisfy validation. If a required value is not yet known, the page is not ready to publish. Body elements follow the requirement rules of the relevant post type and element pages rather than this metadata default.

Write first, apply elements second

Element selection is a classification task, while drafting is a reasoning task. Trying to perform both sentence by sentence makes the writer optimize prematurely for component boundaries. The usual result is weaker transitions, shallow explanations sized to a box, repetitive headings created to satisfy markup, and directives chosen because they are convenient rather than because their purpose matches.

Production therefore happens in two distinct passes:

1. Write the whole article as plain text. Complete the argument, examples, qualifications, transitions, and conclusion. At this stage, headings may describe the draft’s logic, but they do not settle the final element type.
2. Apply elements in a separate top-to-bottom pass. For each heading and block, state its purpose, check the library, wrap matching sections, add declared attributes, and confirm body mapping and nesting.

The separation improves both outputs. The prose develops according to the reader’s questions instead of the current theme’s box sizes, while the markup pass can compare similar blocks consistently across the entire document. It also makes omissions visible: a writer can see that the article contains a warning or definition before deciding how to encode it.

After the structural pass, read the page once without looking at the directive names. Elements must support a coherent article, not turn it into a stack of disconnected widgets. Then inspect the source once without judging the prose, verifying fences, attributes, nested items, paths, and required metadata.

The three-notation contract

An element is defined once by its purpose, canonical fields, allowed values, body mapping, accessibility behavior, structured-output behavior, and version. That definition is the source of truth. The three platform notations are adapters to it, not three independent component designs.

The representative forms explain the mapping; the individual element page publishes its exact supported name and fields. Authors work in the notation required by their publishing workflow, but they do not rename fields, add platform-only meanings, or manually imitate another renderer’s HTML.

The element owner maintains the canonical definition and decides whether a proposed change is compatible or versioned. Hugo and WordPress maintainers own their adapters and test them against shared fixtures: the same title, content, attributes, items, links, and accessibility expectations must survive all three paths. Editorial owners verify purpose and examples. No platform maintainer may redefine the editorial meaning locally; if a platform cannot express the contract, that is an adapter defect or a proposed contract change.

This model allows presentation to differ where platforms require it while keeping semantics stable. Hugo might render server-side HTML and WordPress might store a block comment, but a warning remains a warning, a checklist item remains an item, and the same required fields remain available downstream.

Versioning published elements

Published content was reviewed against the element meaning that existed at publication time. Silently changing that meaning can alter warnings, structured data, accessibility, or imports without an editor touching the page. Versioning protects that editorial approval.

Use the following change policy:

• Compatible renderer change: A visual refinement, performance improvement, or bug fix that preserves purpose, fields, accepted values, body mapping, and output meaning can ship within the current version. Existing pages receive it through the renderer.
• Compatible additive change: A new optional attribute may join the current version only when its absence preserves existing output and every adapter can safely ignore or support it. The definition and platform tests change together.
• Breaking change: A renamed or removed field, a new required field, changed body mapping, changed purpose, changed default with semantic effect, or incompatible nested-item structure creates a new major element version.
• Deprecation: The old version remains renderable for published pages. Its element page identifies the replacement and the migration path; new pages use the current version.
• Migration: A content migration is explicit, scoped, previewed across Markdown, Hugo, and WordPress, and editorially validated before publication. Record which pages changed and why. Do not make a renderer guess how old source should be reinterpreted.

When no version is written in source, the element uses the baseline version defined when this contract was adopted. That implicit baseline must remain stable. New major versions identify themselves using the version mechanism declared on the element page; they do not repurpose the unversioned syntax.

Rollback also matters. Keep the previous renderer and source representation available until migrated pages pass structural, visual, accessibility, and structured-output checks. If a migration fails, restore the previous version mapping rather than flattening the element into free text, which would discard the semantics versioning is meant to protect.

Production review checklist

Use this final review after the prose pass and the element pass:

• Can every non-prose block’s purpose be stated in one verb?
• Was the library searched by that purpose and close synonyms?
• Does every matching purpose use its typed element, even when an H2 and paragraph would look similar?
• Is every remaining free-text passage part of the article’s continuous explanation, analysis, narrative, or transition?
• Do attributes follow {key=value key2="value with spaces" .class}, with spaces quoted and only declared keys used?
• Does the first body heading map to title and the remainder to content, unless the element page declares another mapping?
• Do repeatable children use ::item{key=value} … ::, with parent and item attributes placed at the correct level?
• Are internal links root-relative with leading and trailing slashes, external links absolute, and image paths inside the approved image root?
• Are metadata fields in frontmatter, never body directives, and are all required metadata values complete?
• Can the same canonical fields map without loss to Markdown, Hugo, and WordPress?
• Does any definition change preserve old pages or introduce an explicit version and migration?

This page is a prerequisite for every individual element page. Each element definition must link back to these base rules, then document only its purpose-specific exceptions: supported attributes, required fields, body or item mapping overrides, allowed nesting, exact platform names, and version history. If an element page is silent, the defaults on this page apply.