Custom Listings: Item Schema, Limits, and Examples

A custom listing is a repeatable collection of items that share a small field schema. Each item may have a title, a concise summary, one or two metadata values, and a destination link. That structure gives readers more context than a bullet list without making every item behave like a standalone product card .

Example — supported export formats

• CSV — Tabular rows for spreadsheet analysis. Best for flat records. Availability: All plans. Action: View CSV export setup.
• JSON — Nested records for applications and data pipelines. Best for preserving field relationships. Availability: Pro and Enterprise. Action: Read the JSON reference.
• Google Sheets — A synchronized worksheet for teams that review data without code. Availability: Pro and Enterprise. Action: Connect Google Sheets.

The rendered element should not be a decorative version of those bullets. It should expose one collection containing three items, and each item should preserve the same title, summary, bestFor, availability, and url fields. The field model—not the border, icon, or column count—is what makes the listing custom.

Why this element matters

Ordinary prose hides repetition. If six integrations are described in six paragraphs, a reader must discover that every paragraph contains a system name, supported action, account requirement, and setup link. A custom listing names those recurring parts through one item schema: a defined set of fields used by every item. Readers learn the pattern after the first entry and can scan later entries predictably.

That consistency also improves reuse. A content management system can validate required fields, a template can render every item without page-specific markup, and a downstream application can transform the same source into a compact mobile list or a searchable directory. Search engines and AI systems receive discrete item boundaries rather than having to infer where one entity ends and another begins.

The element matters because there is a common gap between two valid structures. Bullets work when each item is one compact statement. Cards work when each item needs independent imagery, several commercial attributes, a prominent action, or enough visual weight to stand alone. Many collections need neither extreme. An integration list may require a name, a two-sentence capability summary, a status, and a link. Flattening that into bullets loses the fields; inflating it into cards wastes space and makes a reference collection feel promotional.

Structure is not an excuse to make every collection bespoke. A one-off design produces inconsistent fields, ordering, accessibility, and responsive behavior. The element writing rules therefore apply first: identify the repeated information need, register the smallest schema that satisfies it, and keep the content portable across renderers.

When to use it

Use a custom listing when all items answer the same reader question, each needs two to five visible fields, and the primary task is to inspect or navigate rather than compare every value side by side. Suitable collections include integrations, service areas, supported formats, resource downloads, partner types, team responsibilities, directory previews, and grouped features.

Run four tests before choosing it:

1. Repeatability: Can every item use the same required fields without inventing exceptions?
2. Independence: Can a reader understand one item without reading the previous item?
3. Scanning: Is the title-plus-summary pattern more useful than a grid of comparable values?
4. Action: Does each item need no more than one primary destination?

If the answers are yes, a custom listing is likely appropriate. Use another element when the collection fails one of those tests:

• Use a bullet list when items need only one parallel sentence and no separate metadata.
• Use a comparison table when readers must scan the same criteria vertically or horizontally across alternatives.
• Use a product card when image, price, offer, rating, availability, and purchase action make each item a substantial commercial unit.
• Use a step list when position expresses sequence rather than editorial ordering.
• Use a glossary or definition pattern when each entry is fundamentally a term–definition pair.
• Use headings and prose when items require different fields or more than about 100 words of explanation each.

Do not select a custom listing merely because the design calls for repeated boxes. First prove that a stable content model exists. If item one has a price and item two has an author biography while item three has a download size, they are not one collection even if CSS can align them.

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

Place the listing after the page defines the collection and its inclusion rule. “Supported integrations” is a label; “These integrations can send audited pages to an owned reporting workspace” tells readers what membership means. When selection or testing created the set, explain that method before the first item so the listing does not imply unsupported completeness or ranking.

Put the collection close to the decision or navigation task it serves. An integration page should introduce the connection and its outcome before listing supported workflows. A directory should explain scope and filters before showing entries. A listicle should state its evaluation method before presenting selected items.

Do not interrupt a listing with prose, advertisements, calls to action, or unrelated screenshots. Item boundaries must remain consecutive. Place qualifications inside the affected item’s defined metadata or explain a collection-wide condition before or after the whole list. If more than twelve items are necessary, group them beneath meaningful subheadings, add filtering, or route readers to a Directory index . Do not create one endless visual stack.

Anatomy

A complete custom listing has these regions:

1. Collection title: names the set in the reader’s language, not the component’s internal name.
2. Scope statement: defines what qualifies for inclusion and whether the collection is complete, selected, or illustrative.
3. List container: establishes one semantic collection and owns the item count.
4. Item title: uniquely identifies the entity, resource, capability, or option.
5. Item summary: explains the item’s relevant difference or use in one or two sentences.
6. Metadata group: exposes zero to three labeled facts from the registered schema.
7. Primary action: links to one clear destination using descriptive anchor text.
8. Item boundary: uses spacing, a rule, or restrained surface treatment without disconnecting the item from its collection.

The scope statement prevents a common accuracy failure. “Available integrations” implies completeness; “Common reporting integrations” declares a selection. The author must choose the wording the source data can support.

Stay Updated on AI Visibility Trends

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

Email address

Subscribe

Design examples

The renderer may vary density, but it must preserve field order, semantic list structure, and a predictable reading sequence.

Stacked editorial listing

Use the default stacked design when summaries carry most of the value. Keep the title first, summary second, metadata third, and action last. A subtle divider is enough; each item does not need a raised card.

Compact directory preview

Use a compact variant when titles and one metadata value let readers choose a destination. The summary may be shorter, but labels must remain visible. Never replace a meaningful status with an unexplained colored dot.

Grouped listing

Use groups when one stable classification reduces a collection of eight to twenty-four items into sections. Group headings must describe a genuine taxonomy such as export type or service region. Do not group merely to achieve equal columns.

Narrow viewport

At narrow widths, preserve source order and stack metadata beneath the summary. Do not hide fields that remain relevant, shrink text to maintain columns, or move actions away from their item.

Parameters

The schema below is intentionally constrained. A field becomes part of the component only when it is useful across the collection, not because one item happens to have data for it.

Three items are the minimum because a pair is usually clearer as prose, a two-column comparison, or two substantial cards. Twelve is the normal maximum because scanning a long unfiltered stack becomes inefficient. The grouped ceiling of twenty-four is a guardrail, not a target; larger or frequently changing sets need a directory, search, pagination, or a data-driven application.

Choose ordered=true only when the visible order expresses a declared ranking. Editorial convenience, alphabetical sorting, or data-source order does not create a rank. When ranking is real, state the methodology and retain the position in both visible output and any structured data.

Syntax and code examples

The portable directive defines the authored contract. Platform adapters may store the data differently, but they must preserve the same field names, item order, optionality, and visible output.

Portable Markdown directive

:::custom-listing{title="Export formats" variant=stacked}
These are the formats available for sending completed audit records to another workspace.

:::item{id=csv title="CSV" url="/docs/exports/csv/"}
Tabular rows for spreadsheet analysis and flat-file ingestion.

- Best for: Spreadsheet analysis
- Availability: All plans
- Action: View CSV export setup
:::

:::item{id=json title="JSON" url="/docs/exports/json/"}
Nested records that preserve relationships for applications and data pipelines.

- Best for: Automated workflows
- Availability: Pro and Enterprise
- Action: Read the JSON reference
:::

:::item{id=sheets title="Google Sheets" url="/docs/exports/google-sheets/"}
A synchronized worksheet for teams that review data without code.

- Best for: Shared review
- Availability: Pro and Enterprise
- Action: Connect Google Sheets
:::
:::

The example URLs describe the portable syntax only; an implementation must replace them with verified destinations. Do not publish an example path as a live link merely because it appears in a code block.

Hugo adapter

{{< custom-listing title="Export formats" variant="stacked" >}}
  {{< custom-listing-item id="csv" title="CSV" url="/docs/exports/csv/" action-label="View CSV export setup" >}}
  Tabular rows for spreadsheet analysis and flat-file ingestion.

  **Best for:** Spreadsheet analysis  
  **Availability:** All plans
  {{< /custom-listing-item >}}
{{< /custom-listing >}}

This notation specifies a future or project-level adapter; it does not authorize creating a page-local shortcode. All parameters are named. Until an adapter exists, render the collection as semantic HTML with <ul> and <li> or as native Markdown rather than silently dropping the field relationships.

WordPress block

<!-- wp:amicited/custom-listing {"title":"Export formats","variant":"stacked"} -->
<ul class="custom-listing">
  <li data-item-id="csv">
    <h3>CSV</h3>
    <p>Tabular rows for spreadsheet analysis and flat-file ingestion.</p>
    <dl><dt>Best for</dt><dd>Spreadsheet analysis</dd><dt>Availability</dt><dd>All plans</dd></dl>
    <a href="/docs/exports/csv/">View CSV export setup</a>
  </li>
</ul>
<!-- /wp:amicited/custom-listing -->

Native blocks are an acceptable fallback when they produce one list, one list item per entry, real headings, a definition list for labeled metadata, and descriptive links. A generic Columns block is not a reliable substitute because source order and item grouping often break on mobile.

Examples

Good: a consistent resource listing

Migration resources

These resources support teams preparing, executing, and validating a site migration.

1. Redirect mapping worksheet — Records each old URL, its approved destination, owner, and validation status. Format: Spreadsheet. Stage: Planning. Action: Download the redirect worksheet.
2. Launch-day validation script — Checks response codes, redirect chains, canonical targets, and indexability for the migrated URL set. Format: Script. Stage: Launch. Action: Review validation setup.
3. Post-launch monitoring view — Tracks crawl failures and unexpected traffic changes after deployment. Format: Dashboard. Stage: Monitoring. Action: Configure the monitoring view.

This works because each item uses the same five fields: title, summary, format, stage, and action. The scope explains why the resources belong together. Numbering reflects the declared migration stage, not a claim that the first resource is “best.” Each action identifies its destination instead of repeating “Learn more.”

Bad: boxes without a shared model

Helpful things

• SEO checklist — Our favorite guide. Updated recently. Learn more.
• Premium audit — €499, includes a call and report. Five stars. Buy now.
• Viktor — Technical lead based in Bratislava, available Tuesdays.
• API docs — Authentication, limits, errors, examples, SDKs, changelog, status, support, and twenty more topics.

This fails before visual design begins. The set mixes a resource, service, person, and documentation area. Fields change on every item, “recently” has no date, the rating lacks a source and scale, and item depth ranges from a fragment to a section outline. Split the content by purpose, then choose the registered element for each collection. A border around inconsistent data does not create a custom listing.

Bad: a listing that should be a table

Suppose six plans each show monthly price, annual price, user limit, storage, support response, and SSO availability. Readers need to compare the same six values across every plan. A listing would force them to remember plan one while scrolling through plan six. Use a comparison table because the task is cross-item evaluation. If each plan also needs a positioning statement and purchase action, place those outside or alongside the table using the page’s registered plan component; do not duplicate conflicting values in two sources.

Schema markup and accessibility

Render the collection with native list semantics. Use <ul> when item order has no meaning and <ol> when the page declares a genuine sequence or ranking. Every entry belongs in one <li>. Within it, use a real heading at the correct document level, a paragraph for the summary, and <dl>, <dt>, and <dd> for labeled metadata. A screen reader should encounter the item title before its description, facts, and action.

Do not make the entire item an oversized link when it contains another control or several text regions. Give the primary link a descriptive label such as “View CSV export setup.” If a stretched-link pattern is used, its focus indicator must remain visible and its accessible name must still describe the destination. Icons need alternative text only when they communicate information not already present in text. Decorative icons should be hidden from assistive technology.

Visual order and source order must match. A multi-column desktop layout must collapse without reading item one, item three, item five, then item two. Metadata labels cannot disappear just because repeated values appear visually aligned; “Enterprise” alone does not tell a nonvisual reader whether it describes availability, audience, or support.

ItemList structured data is optional, not a default styling hook. Use it when the visible collection is a meaningful finite list and the page benefits from identifying that collection. Map every visible entry to itemListElement. Include position only for a real ordered list, and ensure names, URLs, and counts match the rendered content. Do not mark up navigation menus, arbitrary feature teasers, or a partial set as though they were a complete ranked list. When entries are identifiable entities such as organizations or software applications, use the most specific eligible type only when the page supplies and verifies the required identity data.

Writing rules

1. Explain membership before presenting members. Readers need to know whether the set is complete, selected, sponsored, ranked, or illustrative before they interpret omission or order. State the inclusion rule in the scope sentence.
2. Define one item schema before drafting items. Consistent fields let readers learn one scanning pattern and let validation catch missing content. Register required and optional fields before authors populate the collection.
3. Keep required fields truly universal. A nominally required field that authors fill with “N/A” in half the entries is the wrong field or evidence that the collection contains different item types.
4. Limit visible metadata to three pairs. More fields shift the task toward comparison and make each row hard to scan. Move secondary facts to the destination page or use a table.
5. Write summaries for difference, not repetition. The title already names the item. Use the summary to explain its relevant capability, audience, limitation, or role.
6. Use parallel labels and units. Do not alternate “Plan,” “Available on,” and “Tier” for the same concept. Normalize dates, currencies, units, and status vocabulary before rendering.
7. Give each item one primary action. Competing buttons turn a reference list into a card grid and obscure the intended next step. Put secondary destinations on the detail page.
8. Declare meaningful order. Alphabetical, chronological, ranked, editorial, and source-system orders create different expectations. Name the order when it could affect interpretation.
9. Set minimum and maximum counts. Use three to twelve items normally, with up to twenty-four only in useful groups. Switch patterns when the collection falls outside those boundaries.
10. Maintain one source of truth. If price, status, availability, or another volatile field appears elsewhere, populate every representation from the same owned source and expose a verification date where needed.

Post types that use it

• A Listicle guide uses a custom listing when each selected entry needs the same summary, fit, limitation, and onward link but not a dense comparison matrix.
• A Best-X-for-Y page may use it for audience-specific recommendations after explaining the evaluation method. Ranking must be explicit rather than implied by visual order.
• An Alternatives-to-X page can present replacement options with consistent “best for,” tradeoff, and detail-link fields before a narrower comparison.
• A Category page uses a compact or grouped listing to preview a manageable set of child products or services when filtering is not yet necessary.
• A directory index uses the element only for a preview or a small, stable directory. Large entity sets need search, filters, pagination, and a data-backed directory interface.
• A Company profile can list verified business units, certifications, or locations when every entry shares the same fields.
• A Vendor profile can list supported services, regions, or engagement models without turning the profile into a product grid.
• An Integration page can list supported workflows, data objects, triggers, or destinations using a predictable capability-and-requirement schema.

The presence of a collection does not require this element. Use it only when the custom field model improves retrieval or navigation. A short set of prerequisites still belongs in bullets, and a matrix of capabilities still belongs in a table.

QA checklist

• The collection has a title and a scope sentence that defines inclusion.
• Every item represents the same kind of entity, resource, capability, or option.
• Required and optional fields are documented before content entry.
• Every item has a unique stable ID, title, and 12–60-word summary.
• No item invents a field that is absent from the registered schema.
• The collection contains 3–12 items, or justified groups with no more than 24 total.
• Items have no more than three visible metadata pairs and one primary action.
• Labels, units, statuses, dates, and action wording are consistent.
• Order is declared when it implies ranking, chronology, or priority.
• A table was chosen instead when cross-item comparison is the main task.
• The output uses one semantic <ul> or <ol> with one <li> per item.
• Headings follow the page hierarchy and metadata uses term–description semantics.
• Keyboard focus is visible and links describe their destinations.
• Source order matches visual order at desktop and mobile widths.
• ItemList markup, if present, matches the visible items, order, count, names, and URLs.
• Volatile values come from an owned source and include an appropriate verification date.

FAQ

The questions below resolve the boundaries that most often cause a custom listing to drift into bullets, cards, or tables.

What is a custom listing?

A custom listing is a repeatable collection whose items share a small, named field schema, such as title, summary, metadata, and link. It sits between a simple bullet list and a visually independent card grid.

How many items should a custom listing contain?

Use three to twelve items as the normal editorial range. Two items usually need prose or a side-by-side component. More than twelve need useful grouping, filtering, pagination, or a directory pattern; the grouped variant must not exceed twenty-four items.

When should a custom listing become a table?

Use a table when readers must compare most items across the same three or more fields, especially numeric values, dates, statuses, or yes-or-no capabilities. Keep a listing when summaries and onward links matter more than cross-item comparison.

Does a custom listing need ItemList schema?

No. Add ItemList only when the collection is meaningful and finite, every marked-up item is visible, and any position reflects a declared order. Ordinary navigation, teaser, and related-content listings usually need semantic HTML rather than special schema.

Can items have different fields?

Only optional fields defined by the shared schema may be absent. Do not let authors invent fields per item. If several items need a different information model, split them into another listing or choose a more suitable element.