= Antora Extensions and Macros for Redpanda Docs
:url-org: https://github.com/redpanda-data
:url-project: {url-org}/docs-extensions-and-macros
ifdef::env-github[]
:important-caption: :exclamation:
:note-caption: :paperclip:
endif::[]

This library provides https://docs.antora.org/antora/latest/extend/extensions/[Antora extensions], https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/register/[AsciiDoc macros], and automation tools for Redpanda documentation.

== Quickstart

Install the package:

[,bash]
----
npm i @redpanda-data/docs-extensions-and-macros
----

[,yaml]
----
antora:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version'
asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
----

== Documentation

link:extensions/README.adoc[**Antora extensions**]:: Extensions that enhance the Antora build process

link:macros/README.adoc[**AsciiDoc macros**]:: Custom inline and block macros for documentation

link:mcp/README.adoc[**MCP server**]:: Model Context Protocol server for automating documentation tasks with Claude Code

link:CLI_REFERENCE.adoc[**CLI reference**]:: Complete command reference for `doc-tools`

link:CONTRIBUTING.adoc[**Contributing**]:: Development setup and guidelines

== What's included

=== Antora extensions

Extensions that enhance Antora's build process:

* **Version management** - Automatically fetch latest versions from GitHub
* **Content generation** - Generate indexes, categories, and structured data
* **Navigation** - Manage unlisted pages, redirects, and cross-version links
* **Integrations** - Algolia indexing, EOL banners, related content
* **File processing** - Archive attachments, replace attributes, collect samples

=== AsciiDoc macros

Inline and block macros for documentation:

* `glossterm` - Reference glossary terms with tooltips
* `config_ref` - Link to configuration properties
* `helm_ref` - Link to Helm values
* `components_by_category` - Display Redpanda Connect components
* `component_table` - Searchable component table

=== Documentation automation (MCP server)

A Model Context Protocol server that exposes doc-tools to Claude Code:

* Generate property, metrics, and RPK documentation
* Update connector reference documentation
* Get version information
* Review generated content for quality

== Support

Report issues at {url-project}/issues