Registry metadata: layers, bundles and previews
The registry reads an optional antoraRegistry object from your package.json, or the same keys from the frontmatter of antora-registry.md.
If both set a key, package.json wins.
Anything you leave out, the registry guesses and labels inferred.
Registry admins can override any value from /admin.
{
"name": "@acme/antora-ui-callouts",
"antoraRegistry": {
"layers": ["bolt-on"],
"previews": [
{ "url": "docs/assets/callouts-light.png", "caption": "Callouts, light mode" },
{ "url": "https://acme.dev/callouts-dark.png", "caption": "Callouts, dark mode" }
]
}
}
Layers
Layers use the names from antora-ui-chassisunchecked. List every layer the package changes, most important first.
| Id | Shown as | What it owns |
|---|---|---|
|
Engine |
The Antora pipeline and the UI model data: Antora extensions that run at build time, generators, validators. |
|
Chassis |
Unthemed region parts (header, nav, toolbar, footer slots) and their contracts. |
|
Body kit |
Silhouette and column layout: where the regions sit. |
|
Paint & trim |
Palettes, typography, logo, dark mode and other chrome. |
|
Bolt-ons |
Features added on top, preferably through slots: search, diagrams, tabs, copy buttons. |
paint-trim, paint-and-trim, bolt-ons and bodykit are accepted as aliases.
Unknown ids are ignored.
Entries with no layer, declared or inferred, appear under Unclassified in search.
How the registry guesses
When layers is missing:
-
A bundle takes the union of its members' layers.
-
A repository named
antora-ui-chassis, or one that describes itself as a chassis, ischassis. -
UI modules and recipes that mention dark mode, palettes, colors, icons, logos or fonts are
paint; those that replace layout partials or mention layout, header, masthead or columns arebody-kit; the rest arebolt-on. -
Antora extensions that mention themes or palettes are
paint; the rest arebolt-on.
Guesses show an inferred label next to the layer. Declare layers to remove it.
Bundles
A bundle is a package that composes other extensions, such as a compose pack or a UI recipe. Bundles get a Bundle badge, a contents list on the detail page, and their own kind in search.
Declare a bundle in any of these ways:
-
"bundle": true: members are yourdependencies. -
"bundle": ["@acme/one", "@acme/two"]: an explicit member list. -
"kind": "bundle"or"purpose": "compose-pack"(inantora-registry.md).
The registry also detects bundles, marked detected, when the package has one of the keywords antora-bundle, compose-pack, extension-pack or bundle, or depends on three or more extensions already in the registry.
Previews
previews (or the older screenshots) is a list of { url, caption }.
Relative URLs resolve against your default branch on raw.githubusercontent.com.
Use PNG or WebP, at least 1200 px wide, and show light and dark mode if you support both.
Where previews come from, in order:
-
Images an admin added in
/admin. -
Your declared
previews. -
If you declared none, up to four non-badge images from your README.
The first preview is the card thumbnail; the detail page shows them all as a gallery.
Display title
Cards, search and package headings show a display title, picked in this order:
-
antoraRegistry.titleinpackage.json. -
displayNameinpackage.json. -
The first heading of the package README.
-
The package name, humanized: scope stripped, words split on hyphens and title-cased, acronyms such as UI, CSS and TOC kept.
The raw package name stays visible on the package page and in title tooltips.
Titles are unique
Display titles are unique across the registry, compared ignoring case and punctuation (Color Scheme and color-scheme are the same title). Fork-grouped entries are not counted. The rule is soft: titles are never used to address a package (identity stays host, owner, repository and package), and it never blocks indexing.
-
The entry first indexed with a title holds it.
-
Later entries with the same title are still listed. They show the owner (and GitHub or GitLab when the hosts differ) after the title, and their package page shows a "title already in use" notice. Set a unique
antoraRegistry.titleto clear it. -
When the holder renames or leaves the registry, the title passes to the next earliest entry at the next sync.
Search the registry for your title before you pick one.
"antoraRegistry": {
"title": "Light/Dark Mode",
"antora": "3"
}
An npm name, when the package is published there from the same repository, appears only as extra information: Antora playbooks can point at repository URLs, and npm is never treated as identity.
Full description
The detail page shows the package description as the summary, and a Full description section below it.
Keep the summary to the main behavior in plain, complete sentences, and put exceptions, opt-outs and optional parts in the full description.
The full description comes from, in order:
-
longDescriptioninantoraRegistry(or theantora-registry.mdfrontmatter). Separate paragraphs with a blank line (\n\nin JSON);codespans in backticks are kept. -
Otherwise, your README intro: the prose before the first second-level heading (
==in AsciiDoc,##in Markdown), without the title, badges, images or HTML, capped at three paragraphs.
The registry never shows the whole README; the section ends with a Read the full README link to the repository.
{
"description": "Antora extension that adds an Ask box to Lunr search.",
"antoraRegistry": {
"longDescription": "Lunr answers first.\n\nA remote backend is optional. Without it, the box behaves as plain Lunr search."
}
}
Antora version compatibility
The registry lists each tagged release of a repository and the Antora line it targets, so a theme or extension can ship different releases for Antora 3 and Antora 4 (antora-solid). The sync reads the repository’s GitHub releases and tags (newest 40 full SemVer releases; repositories with more than three packages keep the newest 12) and resolves each release’s compatibility. The first rule that matches wins:
-
Build metadata on the tag.
v4.2.0+antora.3means Antora 3;+antora-solidmeans Antora 4. An alias tag on the same version (v4.2.0released,v4.2.0+antora.3tagged next to it) counts for that release and is not listed twice. -
engines.antorainpackage.jsonat that tag, as an npm range:"^3.1.0",">=3 <5". -
Peer dependencies on core Antora packages (
antora,@antora/site-generator,@antora/cliand the other pipeline packages) inpackage.jsonat that tag. Add-ons such as@antora/lunr-extensionversion on their own and are ignored. -
Repository default:
antoraRegistry.antorainpackage.jsonon the default branch:"3",4,"antora-solid"or[3, 4]. -
Otherwise the release is shown under "Antora version not declared". Nothing is guessed.
Rolling tags such as v4 or v4.2 take the compatibility of the newest full release they cover and are marked "rolling".
Each release lists its install spec (github:owner/repo#tag) and its release assets, such as ui-bundle.zip.
The package page shows a Releases by Antora version table, grouped by Antora line with the latest stable release of each line highlighted.
Cards show an "Antora N" badge for every line with a release, and the extensions page has an Antora version filter (Antora 3, Antora 4).
Releases are stored in the entry payload and in the catalog_release table (one row per repository and tag), which drizzle-kit push creates before each sync and deploy.
"engines": { "antora": "^3.1.0" },
"antoraRegistry": { "antora": "3" }
Color schemes
A paint can list its color schemes so the registry shows them as swatches on the card and with labels on the package page.
Point antoraRegistry.colorSchemes at the paint CSS (a path or a list of paths on the default branch).
The file starts with a @color-schemes comment mapping each scheme id to a label, optional slots (["dark"] for a dark scheme, [] for a special one) and an optional base:
/* @color-schemes
{ "light": {"label":"Strawberry (light)"}, "orangedark": {"label":"Orange (dark)","slots":["dark"]} }
*/
:root { --sk-canvas: #ffebee; --sk-dominant: #ff002b; --sk-link: #0042db; --sk-ink: #1e050a; }
html.dark-theme[data-scheme="orangedark"] { ... }
Swatch colors come from the scheme’s own block: light is :root, dark is html.dark-theme, and any other id is html[data-scheme="id"] or html.dark-theme[data-scheme="id"].
The registry takes up to four hex custom properties from it: canvas or background, the dominant or accent color, the link color, and the text color.
Documentation link
Extension pages show a Docs button next to Repository. The registry picks the first of:
-
antoraRegistry.docs(anhttps://URL), -
package.json
homepage, unless it points at the repository itself (for example…/repo#readme), -
the repository’s About URL (GitHub or GitLab homepage),
-
a known Antora docs site for the repository.
In a monorepo each package’s own package.json is used.
{ "antoraRegistry": { "docs": "https://example.org/my-extension/" } }
Canonical entries and variants
One thing, one listing. When several packages are ways of using the same feature (a module, a one-require extension, a recipe), pick one canonical entry and nest the others under it. When a package is replaced, point it at its replacement.
| Field | Meaning |
|---|---|
|
|
|
Optional. One line for the Ways to use it list (else the package |
|
Id of the entry that replaces this one. The entry is hidden from listings and search, makes no title claim (so it is never a title clash), and its page shows "Replaced by <title>" with a link. Use it for deprecated or compatibility repos, not for alternatives that are still maintained. |
A search that matches a variant’s title, package name or keywords returns the canonical entry, with a note naming the matching variant. Chains resolve to the final entry; an unknown or circular target is ignored and the entry stays listed.
In a monorepo, set the fields in each package’s own package.json. A repository whose entries need different values, or one you do not own, is grouped by the registry’s curated list (src/data/catalog-groups.ts); declared values win over curated ones.
{
"name": "antora-dark-mode",
"antoraRegistry": {
"title": "Antora Dark Mode",
"variantOf": "github.com/antora-supplemental/antora-ui-chassis/light-dark-mode",
"variantLabel": "One require for the Default UI: toggle, palette and paint in a single Antora extension"
}
}
Example: a compose pack
---
name: "Facto stack"
description: "Valentus chrome plus the Facto extensions, wired together."
purpose: compose-pack
layers: [chassis, body-kit, paint, bolt-on]
previews:
- url: "docs/assets/facto-light.png"
caption: "Facto stack demo, light"
---
Package compatibility
Declare how your package relates to others in package.json under antoraRegistry. Ranges are semver. Keys are package names, owner/repo, or repository names.
"antoraRegistry": {
"requires": { "@antora-supplemental/color-scheme": "^0.4.0" },
"worksWith": { "valentus-theme": "^4.1.0" },
"conflictsWith": { "antora-dark-mode": "*" },
"provides": { "skittles-paint-tokens": "0.1" },
"uses": { "valentus-layout-markup": "4", "color-scheme-tokens": "^0.4", "light-dark-slots": "^0.1" }
}
requires,worksWith,conflictsWith-
Direct relations.
requiresimpliesworksWith. Relations are shown on both packages. provides,uses-
Contracts: named, versioned interfaces such as
[email protected],[email protected],valentus-layout-markup@4,default-ui-markup@2,antora-ui-model@3.
The registry computes links at each catalog sync, stores them in the entry snapshot and the catalog_compat table, and shows them on the detail page under Works with (prominent) and Conflicts with (smaller), with the reasoning in a tooltip.
Confidence and precedence
-
Declared conflict: always wins.
-
Antora mismatch: two related packages that share no Antora major get a warning instead of "works with".
-
Guaranteed: a package provides every contract the other uses, or a cross-layer chain A → B → C has strict layering: every contract A uses is provided by B or C at a compatible version, every contract B uses is provided by C, A does not reach C’s contracts directly, and the current B version satisfies the ranges both A and C declare.
-
Declared (or Curated, for registry seeds of packages that cannot declare yet): from
requires/worksWith. -
Likely (inferred): any other declared chain, with the reason (for example "A reaches C’s markup directly, not via B").
-
Alternative: lowest. Declared relations and satisfied contracts always take precedence over layer inference.
Layers are either exclusive or composable:
-
Exclusive (one per site): engine, body kit (layout), paint. Two packages in the same exclusive layer are listed as alternatives only when neither declares
requires/worksWithtoward the other and neither’susescontracts are provided by the other. -
Composable (sets of cooperating packages): chassis, extensions/bolt-ons. Alternatives are never inferred there; for example
light-dark-modeandcolor-schemeare both chassis packages and work together.
Packages in the same monorepo that declare relations to each other are never alternatives. A declared name resolves by the package’s package.json name (for example @antora-supplemental/color-scheme), its catalog id, or its repository.