Contributing your Extension

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

  1. package.json: Standard npm package file. The registry uses the name, version, and description fields.

  2. 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

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

Recommended topics by content type

These are conventions for this registry; align your topics so future automation can classify listings. Theme gallery submissions live at registry.antora-supplemental.org/themes — use prescribed antora-theme topics plus appearance tags (antora-light-theme, antora-dark-theme, etc.), not repo/product names.

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-ui-theme, or antora-theme, or antora-site-theme

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

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.