Skip to content

README.adoc

Latest commit

 

History

History
135 lines (103 loc) · 4.17 KB

README.adoc

File metadata and controls

135 lines (103 loc) · 4.17 KB

Antora Extensions

Table of Contents

Documentation for Antora extensions that enhance the documentation build process.

What are Antora extensions?

Antora extensions are Node.js modules that extend Antora’s capabilities during the documentation site build. These extensions can modify content, generate new pages, integrate with external services, and customize the build pipeline.

Documentation

User guide

How to use and configure Antora extensions in your playbook

  • Installation and setup

  • Configuring extensions

  • Common usage patterns

  • Troubleshooting

Reference

Complete reference for all available extensions

  • Extension descriptions

  • Configuration options

  • Environment variables

  • Examples for each extension

Development guide

How to develop new Antora extensions

  • Extension architecture

  • Creating new extensions

  • Testing and debugging

  • Best practices

Quickstart

Install the package

npm i @redpanda-data/docs-extensions-and-macros

Configure in your playbook

antora:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version'
Important
 Extensions must be registered under the antora.extensions key in your playbook, not asciidoc.extensions.

Available extensions

Version management

  • set-latest-version - Automatically fetch latest versions from GitHub releases

Content generation

  • generate-index-data - Generate searchable indexes from content

  • generate-rp-connect-categories - Generate Redpanda Connect component categories

  • generate-rp-connect-info - Generate Redpanda Connect component information

Navigation

  • unlisted-pages - Manage pages that appear in navigation but aren’t listed

  • produce-redirects - Generate redirect configurations

  • unpublish-pages - Mark pages as unpublished

Integrations

  • algolia-indexer - Index content for Algolia search

  • compute-end-of-life - Calculate and display EOL information

  • find-related-docs - Find and link related documentation

  • find-related-labs - Find and link related lab exercises

File processing

  • archive-attachments - Archive file attachments

  • replace-attributes-in-attachments - Replace AsciiDoc attributes in attached files

  • collect-bloblang-samples - Collect Bloblang code samples

Git integration

  • git-full-clone - Ensure full git clones for accurate git dates

  • add-git-dates - Add git-based created and modified dates to pages

Content enhancement

  • add-global-attributes - Add attributes globally to all pages

  • add-pages-to-root - Add pages to the root navigation

  • process-context-switcher - Handle context-dependent content

  • validate-attributes - Validate AsciiDoc attributes

AI-friendly documentation

  • convert-to-markdown - Export documentation pages as markdown with frontmatter

  • convert-llms-to-txt - Generate llms.txt and component-specific exports for AI agents

  • add-llms-directive - Inject llms.txt discovery directive into HTML pages

  • add-markdown-urls-to-sitemap - Add markdown URL entries to sitemap.xml

  • convert-sitemap-to-markdown - Generate markdown sitemap indexes

See Reference documentation for complete details on each extension.

Common use cases

Automatically update version numbers

antora:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version'

Enable Algolia search

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/algolia-indexer'
      algolia_app_id: YOUR_APP_ID
      algolia_api_key: YOUR_API_KEY
      algolia_index_name: YOUR_INDEX

Generate redirects

antora:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'