Contributing your Extension :: Antora Extensions Registry

To list your extension in the Antora Extensions Registry, you should provide metadata files in your repository. This allows the registry to display rich information about your extension, including descriptions and screenshots.

Required Files

package.json: Standard npm package file. The registry uses the name, version, and description fields.
antora-registry.md: A special Markdown file for registry-specific metadata.

The `antora-registry.md` File

This file allows you to customize how your extension appears in the registry. It should be placed in the root of your repository.

Frontmatter Fields

The registry parses the YAML frontmatter for specific fields:

Field Description

Field	Description
`name`	(Optional) Display name if different from `package.json`.
`description`	A short, catchy summary for the extension card (limited to ~150 characters).
`screenshots`	A list of objects containing `url` and `caption`. These will be displayed in the screenshot carousel.

name

(Optional) Display name if different from package.json.

description

A short, catchy summary for the extension card (limited to ~150 characters).

screenshots

A list of objects containing url and caption. These will be displayed in the screenshot carousel.

Content

Everything below the frontmatter is used as the detailed description in the extension’s "Insights" panel. Standard Markdown is supported.

Template

You can use the following template as a starting point. [Download Template]

---
name: "My Awesome Extension"
description: "Briefly explain what your extension does and why it's great."
screenshots:
  - url: "https://raw.githubusercontent.com/user/repo/main/docs/assets/screenshot1.png"
    caption: "Desktop View - Features highlighted"
  - url: "https://raw.githubusercontent.com/user/repo/main/docs/assets/screenshot2.png"
    caption: "Responsive Mobile Layout"
---

# Overview

Add a detailed description of your extension here. You can use **Markdown** to format your content.
This content will be displayed in the "Insights" panel of the Antora Extensions Registry.

## Key Features
- Feature 1
- Feature 2
- Feature 3

Image Guidelines

External Hosting: We do not host your images. Please use stable URLs (e.g., GitHub raw links).
Aspect Ratio: We recommend a 16:9 aspect ratio for best display results.
Format: Standard web formats like PNG, JPG, or WebP are supported.
Count: You can provide up to 5 screenshots.

GitHub Topics (planned auto-discovery)

GitHub repository topics (not Git tags) are a lightweight way to opt into discovery. When automated indexing is enabled for this registry, crawlers will use the public GitHub Search API, for example topic:antora-extension fork:false.

Why a topic can appear before anyone used it

GitHub maintains a topic catalog (GET /search/topics). Several Antora-related names (for example antora-ui-theme, antora-ui-plugin, antora-theme) share the same catalog created_at timestamp in GitHub’s API, which means GitHub added them as recognized topic strings in bulk. That is why the topic picker may suggest antora-ui-theme even when the topic page still shows few repositories — the string exists in GitHub’s suggestion index independently of your repo.

To explore the live catalog and sample repository counts from your machine, run:

pnpm run discover:github-topics
# optional: GITHUB_TOKEN=... pnpm run discover:github-topics
pnpm exec tsx scripts/github-topic-discovery.ts --repos antora-extension

Registry kind	Suggested GitHub topics
Playbook / generator extension (npm-style)	`antora-extension` (and usually `antora`)
Extension bundle	`antora-bundle`
Full UI theme (default-UI-style repo)	`antora-theme` (or `antora-ui-theme` / `antora-site-theme`) plus appearance tags plus the product topic (repo name)
Supplemental UI, components, styles, kits	`antora-ui`, `antora-ui-components`, `antora-ui-styles`, `antora-ui-kit`
UI-level plugin	`antora-ui-plugin`
Generic Antora plugin naming	`antora-plugin`
Documentation site or doc tooling (broad)	`antora-site`, `antora-docs`
Docs / playbook repo that uses a named UI theme	That theme’s product topic (exact GitHub repo name), for example `valentus-theme`

Product dependency topics (required for theme consumers)

Problem: Capability topics (antora-theme, …) classify what kind of thing a repo is. They do not answer “which sites pin Valentus?” when you need to roll a chrome fix.

Rule: Every published Antora UI theme picks a product topic equal to its GitHub repository name (kebab-case), for example valentus-theme or architexture-theme.

Theme repository: carry the product topic alongside gallery/capability topics.
Dependent repositories (Antora playbooks that set ui.bundle.url to that theme’s release, or vendor its supplemental-ui): add the same product topic.

Rediscover with GitHub Search: topic:valentus-theme (or gh search repos --topic valentus-theme).

Theme authors should document the rule in their install guide and keep a knownDependents list in root antora-registry-topics.json5 (optional seed for maintainers). Apply theme + dependent topics with:

node scripts/apply-registry-topics.mjs path/to/antora-registry-topics.json5
# merge-adds productTopic onto knownDependents without wiping other topics

Example Valentus guide: github-topics.adoc.

Forks and ownership (policy sketch)

Automated listing should not mirror every personal fork.

Default filter: only repositories where GitHub reports fork: false in search (fork:false in the search query).
Explicit forks: allow a fork only if maintainers later support a claim flow (for example sign in with GitHub and prove admin on the repo) or a manual allowlist (for official org splits).
Duplicate networks: prefer the repository that is the source of the fork network when both carry the same topic, unless a claimed fork is designated as canonical.

Exact rules will be documented here once the indexer ships; until then, follow the manual contributing flow above.

Contributing your Extension