Antora Extensions and Macros for Redpanda Docs

Contents

Prerequisites
Antora Extensions
Asciidoc Extensions
- Add line numbers and highlights
Macros
Development quickstart

This library provides Antora extensions and Asciidoc macros developed for Redpanda documentation.

Prerequisites

To use this library, you must have Node.js 16 or higher installed on your machine.

node --version

If this command fails with an error, you don’t have Node.js installed.

When you have Node.js installed, use the following command to install the antora-extensions-and-macros package in your project:

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

To use the development version, refer to the Development Quickstart.

Antora Extensions

This section documents the Antora extensions provided by this library and how to configure them.

❗	Ensure you register each extension under the `antora.extensions` key in the playbook, not the `asciidoc.extensions` key.

Add Bloblang samples to pages

The collect-bloblang-samples extension processes Bloblang examples from YAML files in the examples directory of the redpanda-connect component. This extension ensures that these examples are accessible as structured data for use in UI components or documentation, such as sample dropdowns in a Bloblang playground.

It validates, sorts, and attaches the processed examples as a JSON object to the Antora page attributes. The extension ensures examples have unique titles, mandatory fields (input and mapping), and are sorted in alphabetical order.

The processed examples are added as JSON to the page-bloblang-samples attribute. For example:

{
  "hello-world.yaml": {
    "title": "Hello world",
    "input": "{\n  \"message\": \"hello world\"\n}\n",
    "mapping": "root.message = this.message.uppercase()\n"
  },
  "array-processing.yaml": {
    "title": "Array processing",
    "input": "{\n  \"numbers\": [1, 2, 3, 4, 5]\n}\n",
    "mapping": "root.even_numbers = this.numbers.filter(n -> n % 2 == 0)"
  }
}

Environment variables

This extension does not require any environment variables.

Configuration options

To enable the extension, add it to your Antora playbook under the antora.extensions key. No additional configuration is required.

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/collect-bloblang-samples'

Example Bloblang YAML file

The following YAML file is an example of how to define a Bloblang sample:

title: Hello world
input: |
  {
    "message": "hello world"
  }
mapping: |
  root.message = this.message.uppercase()

Add pages to root

The add-pages-to-root extension allows you to copy files from your Antora content catalog to the root of the site during the build process. This is particularly useful for files like llms.txt or any custom files that need to be directly accessible at the site’s root level.

This extension processes a list of file paths provided in the playbook configuration, locates those files in the Antora content catalog, and adds them to the site’s root directory during the publishing phase. Each file’s content and basename are preserved in the process.

Environment variables

This extension does not require any environment variables.

Configuration options

Add the add-pages-to-root extension to your Antora playbook under the antora.extensions key, and specify the list of files to process in the files configuration.

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-pages-to-root'
      files:
        - home:ROOT:attachment$custom-file.txt

Registration example

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-pages-to-root'
      files:
        - home:ROOT:attachment$custom-file.txt

Algolia indexer

This extension generates an Algolia index for each version of each component. The index entries are then saved to Algolia using the saveObjects() method, and also saved as JSON files in the site catalog. JSON files are published to the site root using the template algolia-<component>-<version>.json.

📎	Only pages that include an `<article>` element with the `doc` class are indexed.

Environment variables

ALGOLIA_ADMIN_API_KEY (required)
ALGOLIA_APP_ID (required)
ALGOLIA_INDEX_NAME (required)

Configuration options

The extension accepts the following configuration options:

excludes (optional): Any elements, classes, or IDs that you want to exclude from the index.
index-latest-only (optional): Whether to index all versions or just the latest version of a component.

Registration example

antora:
  extensions:
  - require: '@redpanda-data/docs-extensions-and-macros/extensions/algolia-indexer/index'
    excludes: ['.thumbs','script', '.page-versions','.feedback-section','.banner-container']
    index-latest-only: true

Archive attachments

The archive-attachments extension automates the packaging of specific attachment files into a compressed archive (.tar.gz) based on configurable patterns. This archive is then made available to the generated site, allowing users to easily download grouped resources such as Docker Compose configurations.

This extension enables you to define which files and directories to include in the archive, ensuring that only relevant content is packaged and accessible.

Environment variables

This extension does not require any environment variables.

Configuration options

The extension accepts the following options in the Antora playbook.

Configure the extension in your Antora playbook by defining an array of archive configurations under data.archives. Each archive configuration includes:

output_archive (string, required): The name of the generated archive file.
component (string, required): The name of the Antora component whose attachments should be archived.
file_patterns (array of strings, required): Glob patterns specifying which attachment paths to include in the archive.

📎	Ensure that `file_patterns` accurately reflect the paths of the attachments you want to archive. Overly broad patterns may include unintended files, while overly restrictive patterns might exclude necessary resources.

Example configuration

Here’s an example configuration to enable the extension:

antora:
  extensions:
    - require: '../docs-extensions-and-macros/extensions/archive-creation-extension.js'
      data:
        archives:
          - output_archive: 'redpanda-quickstart.tar.gz' (1)
            component: 'ROOT' (2)
            file_patterns:
              - '**/test-resources/**/docker-compose/**' (3)

Defines the name of the generated archive placed at the site root.
Defines the name of the component in which to search for attachments.
Lists the glob patterns to match attachment paths for inclusion in the archive.
- **: Matches any number of directories.
- /test-resources/: Specifies that the matching should occur within the test-resources/ directory.
- /docker-compose/: Targets the docker-compose/ directory and all its subdirectories.
- **: Ensures that all files and nested directories within docker-compose/ are included.

Behavior with multiple components/versions

Scenario: Multiple components and/or multiple versions of the same component contain attachments that match the defined file_patterns.

Outcome: Separate archives for each component version.

For each matching (component, version) pair, the extension creates a distinct archive named <version>-<output_archive>. For example: 24.3-redpanda-quickstart.tar.gz.

These archives are placed at the site root, ensuring they are easily accessible and do not overwrite each other.

For the latest version of each component, the extension also adds the archive using the base output_archive name. As a result, the latest archives are accessible through a consistent filename, facilitating easy downloads without needing to reference version numbers.

Because each archive has a unique filename based on the component version, there is no risk of archives overwriting each other. The only exception is the archive for the latest version, which consistently uses the output_archive name.

Component category aggregator

This extension maps Redpanda Connect component data into a structured format:

Maps original component names to common names.
Populates connectCategoriesData and flatComponentsData attributes.
Skips deprecated components.

Environment variables

This extension does not require any environment variables.

Configuration options

There are no configurable options for this extension.

Registration example

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories'

Generate index data

The generate-index-data extension creates structured index data about doc pages based on configurable filters. The indexed data is saved to a specified attribute in all component versions, enabling the dynamic generation of categorized links and descriptions within your docs using UI templates.

This extension allows you to define multiple indexing criteria, such as component, URL filter, and environment type.

The generated data is an array of objects, where each object represents a component version. Each object contains the following properties:

component (string): The name of the Antora component.
version (string): The version of the component.
pages (array): A list of pages that match the indexing criteria. Each page contains:
- title (string): The title of the doc page.
- url (string): The URL of the doc page relative to the site root.
- description (string): A brief description sourced from the :description: attribute in the AsciiDoc file. Defaults to an empty string if not provided.

Example:

[
  {
    "component": "ROOT",
    "version": "24.3",
    "pages": [
      {
        "title": "Manage Debug Bundles in Redpanda Console",
        "url": "/current/console/ui/generate-bundle/",
        "description": "Learn how to generate, download, and delete debug bundles in Redpanda Console for comprehensive cluster diagnostics."
      },
    ]
  }
]

Environment variables

This extension does not require any environment variables.

Configuration options

The extension accepts the following options in the Antora playbook.

📎	Ensure filters are well-defined to minimize unnecessary processing. Avoid overly broad configurations in `data.sets`.

data.sets (required): An object defining one or more indexing configurations. Each configuration (or set) accepts the following options:
- component (string, required): The Antora component to search for pages.
- attribute_name (string, required): The attribute name to assign the generated index data. This allows pages and templates to reference the index.
- filter (string, optional): A substring to match within page URLs.
- env_type (string, optional): Matches pages with environment-specific attributes (e.g., Docker, Kubernetes).
- output_file (string, optional): Save the generated index data as a JSON file at the specified path. If not provided, no file is created.

Example configuration

Here’s an example configuration to enable the generate-index-data-extension:

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data-extension'
      data:
        sets:
          console_ui:
            component: ROOT  # Search the ROOT component
            filter: console/ui # Filter pages containing this substring in their URL
            attribute_name: console-ui-index # Save the result in this attribute
            output_file: redpanda-labs/console-ui-index.json # Save data to this file
          docker_labs:
            component: redpanda-labs
            filter: docker-compose
            env_type: Docker
            attribute_name: docker-labs-index

Use the generated data

The index data can be referenced in AsciiDoc pages by specifying the following required attributes:

= CONSOLE UI
:page-index-data: console-ui-index (1)
:page-role: index-list (2)

The attribute whose data you want to display on the page. This must match an attribute configured in the extension.
The page role. This role specfies the UI template that renders the data in the page-index-data on the page.

You can optionally display pages only if they match the component and version of the current Asciidoc page by adding the :page-match-component-version: attribute.

= CONSOLE UI
:page-index-data: console-ui-index
:page-role: index-list
:page-match-component-version: ''

Redpanda Connect tag modifier

This extension updates the playbook to use the latest release tag for the Redpanda Connect documentation. It ensures that the Redpanda Connect documentation is always pulled from the latest release tag available on GitHub.

Environment variables

REDPANDA_GITHUB_TOKEN (optional): A Personal access token (PAT) that has repo permissions for the redpanda-data GitHub organization.

📎

If you don’t set the environment variable, the latest version of Redpanda Connect may not be fetched. When the environment variable is not set, the extension sends unauthenticated requests to GitHub. Unauthenticated requests may result in hitting the API rate limit and cause GitHub to reject the request. In this case the fallback version is used. This version is defined in the playbook where the extension is registered.

Configuration options

There are no configurable options for this extension.

Registration Example

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/modify-connect-tag-playbook'

Version fetcher

This extension fetches the latest release versions from GitHub.

The following attributes are available to all versions of all Antora components:

latest-console-version: The latest release version of Redpanda Console. latest-connect-version: The latest release version of Redpanda Connect. redpanda-beta-version: The latest RC version of Redpanda. redpanda-beta-commit: The commit hash for the latest RC version of Redpanda.

The following attributes are available to the latest version of the ROOT component (Redpanda docs):

full-version: The latest release version of Redpanda. latest-release-commit: The commit hash for the latest release version of Redpanda. latest-operator-version: The latest release version of the Redpanda Operator. latest-redpanda-helm-chart-version: The latest release version of the Redpanda Helm chart.

Environment variables

REDPANDA_GITHUB_TOKEN (optional): A Personal access token (PAT) that has repo permissions for the redpanda-data GitHub organization.

📎	If you don’t set the environment variable, the latest versions may not be fetched. When the environment variable is not set, the extension sends unauthenticated requests to GitHub. Unauthenticated requests may result in hitting the API rate limit and cause GitHub to reject the request.

Registration example

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

Validate attributes

This extension ensures the consistency and validity of page attributes, focusing on validating page categories against a predefined list of valid categories and subcategories. It automatically adds missing parent categories for any specified subcategories and removes any specified categories that are invalid. Additionally, it processes specific environment attributes, setting corresponding page-level attributes when environment conditions are met.

Environment variables

This extension does not require any environment variables.

Configuration options

There are no configurable options for this extension. It operates based on site attributes defined in add-global-attributes.js to determine valid categories and subcategories.

Registration example

Register the validate-attributes extension in the Antora playbook under the antora.extensions key like so:

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/validate-attributes.js'

This extension enhances the connectivity between lab exercises and relevant documentation by dynamically identifying and linking related documentation pages and other lab exercises based on shared categories and deployment types.

Environment variables

This extension operates without requiring any specific environment variables.

Configuration options

This extension does not offer configurable options. It uses the inherent attributes of pages to determine relationships based on page-categories and deployment types (env-kubernetes, env-linux, env-docker, page-cloud).

Registration example

To integrate the related-docs-extension into your Antora playbook, add it under the antora.extensions key as demonstrated below:

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/related-docs-extension.js'

This extension enriches documentation pages with links to related lab exercises, facilitating a deeper understanding of the content through practical application. It dynamically assigns related labs to each documentation page based on shared categories and deployment types.

Environment variables

This extension does not require any environment variables.

Configuration options

The extension operates without explicit configuration options. It automatically processes documentation pages to identify and link related labs based on shared page-categories attributes and deployment types (env-kubernetes, env-linux, env-docker, page-cloud).

Registration example

Include the related-labs-extension in the Antora playbook under the antora.extensions key as follows:

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/related-labs-extension.js'

Global attributes

This extension collects Asciidoc attributes from the shared component or a local YAML file and makes them available to all component versions. Having global attributes is useful for consistent configuration of local and production builds.

Environment variables

This extension does not require any environment variables.

Configuration options

The extension accepts the following configuration options:

attributespath (optional): Specifies the path to a local YAML file that contains global attributes. If this is provided, the extension will load attributes from this file first. If this path is not provided or no valid attributes are found in the file, the extension will fall back to loading attributes from the shared component.

Registration example

antora:
  extensions:
  - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes'
    attributespath: './local-attributes.yml'

In this example, the attributespath option points to a local YAML file (./local-attributes.yml), which contains the global attributes. The extension will load attributes from this file first before falling back to the shared component.

Produce redirects (customization of core Antora)

This extension replaces the default produceRedirects() function in Antora to handle redirect loops caused by page aliases. Normally, page aliases in Antora are used to resolve outdated links without causing issues. However, with indexify, the same URL may inadvertently be used for both the source and target of a redirect, leading to loops. This problem is recognized as a bug in core Antora. For example, creating a page alias for modules/manage/security/authorization.adoc to point to modules/manage/security/authorization/index.adoc' can lead to a redirect loop where `manage/security/authorization/ points to manage/security/authorization/. Furthermore, omitting the alias would lead to xref not found errors because Antora relies on the alias to resolve the old xrefs. This extension is necessary until such behaviors are natively supported or fixed in Antora core.

Environment variables

This extension does not require any environment variables.

Configuration options

There are no configurable options for this extension.

Registration example

antora:
  extensions:
  - '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects'

Replace attributes in attachments

This extension automates the replacement of AsciiDoc attribute placeholders with their respective values within attachment files, such as CSS, HTML, and YAML.

📎	The `@` character is removed from attribute values to prevent potential issues with CSS or HTML syntax. If the same attribute placeholder is used multiple times within a file, all instances will be replaced with the attribute’s value.

Environment variables

This extension does not require any environment variables.

Configuration options

The extension accepts the following configuration options in the Antora playbook:

data.replacements (required)

An array of replacement configurations. Each configuration can target multiple components and define specific file patterns and custom replacement rules.

components (array of strings, required): Lists the names of the Antora components whose attachments should undergo attribute replacement.
file_patterns (array of strings, required): Glob patterns specifying which attachment files to process. These patterns determine the files that will undergo attribute replacement based on their paths within the content catalog.
custom_replacements (array of objects, optional): Defines custom search-and-replace rules to be applied to the matched files. Each rule consists of:
- search (string, required): A regular expression pattern to search for within the file content.
- replace (string, required): The string to replace each match found by the search pattern.

📎	Ensure that `file_patterns` accurately reflect the paths of the attachments you want to process. Overly broad patterns may include unintended files, while overly restrictive patterns might exclude necessary resources.

Registration Example

This is an example of how to register and configure the replace-attributes-in-attachments extension in your Antora playbook. This example demonstrates defining multiple replacement configurations, each targeting different components and specifying their own file patterns and custom replacements.

antora:
  extensions:
    - require: './extensions/replace-attributes-in-attachments'
      data:
        replacements:
          - components:
              - 'ROOT'
              - 'redpanda-labs'
            file_patterns:
              - '**/docker-compose.yaml'
              - '**/docker-compose.yml'
            custom_replacements:
              - search: ''\\$\\{CONFIG_FILE:[^}]*\\}''
                replace: 'console.yaml'
          - components:
              - 'API'
            file_patterns:
              - '**/api-docs/**/resources/**'
            custom_replacements:
              - search: '\\$\\{API_ENDPOINT:[^}]*\\}'
                replace: 'https://api.example.com'

Aggregate terms

This extension aggregates all term pages from the shared component and does the following:

Makes all term-name, hover-text, and link attributes available to the glossterm macro.
Looks for glossary pages named reference:glossary.adoc in all versions of all components and appends the contents of each term file to the glossary in alphabetical order.
If a glossary page is found, sets the glossary-page attribute of the glossterm macro to reference:glossary.adoc so that terms can be linked to the glossary page.

Environment variables

This extension does not require any environment variables.

Configuration options

The extension accepts the following configuration options:

termspath (optional): Specifies the path to a local directory containing term files (in .adoc format). If this path is provided, the extension will attempt to load terms from this directory first. If this path is not provided or no valid terms are found in the specified directory, the extension will fall back to loading terms from the shared component.

Term files should follow the following structure:

:category: Documentation
:hover-text: This is a description of the term.
:link: https://example.com

== Term Title

This is the detailed description of the term.

Registration example

antora:
  extensions:
  - require: '@redpanda-data/docs-extensions-and-macros/extensions/aggregate-terms'
    termspath: './local-terms/'

In this example, the termspath option points to a local directory (./local-terms/), where the term files are stored. The extension will load terms from this directory first before falling back to the shared component.

Unlisted pages

This extension identifies and logs any pages that aren’t listed in the navigation (nav) file of each version of each component. It then optionally adds these unlisted pages to the end of the navigation tree under a configurable heading.

❗	By default, this extension excludes components named 'api'. This behavior is hardcoded and cannot be changed in the configuration.

Environment variables

This extension does not require any environment variables.

Configuration options

This extension accepts the following configuration options:

addToNavigation (optional): Whether to add unlisted pages to the navigation. The default is false (unlisted pages are not added).
unlistedPagesHeading (optional): The heading under which to list the unlisted pages in the navigation. The default is 'Unlisted Pages'.

Registration example

antora:
  extensions:
  - require: '@redpanda-data/docs-extensions-and-macros/extensions/unlisted-pages'
    addToNavigation: true
    unlistedPagesHeading: 'Additional Resources'

Asciidoc Extensions

This section documents the Asciidoc extensions that are provided by this library and how to configure them.

❗	Be sure to register each extension under the `asciidoc.extensions` key in the playbook, not the `antora.extensions` key.

Add line numbers and highlights

This extension adds the necessary classes to make line numbers and line highlighting work with Prism.js.

Registration example

antora:
  extensions:
  - '@redpanda-data/docs-extensions-and-macros/asciidoc-extensions/add-line-numbers-highlights'

Macros

This section documents the Asciidoc macros that are provided by this library and how to configure them.

❗	Be sure to register each extension under the `asciidoc.extensions` key in the playbook, not the `antora.extensions` key.

config_ref

This inline macro is used to generate a reference to a configuration value in the Redpanda documentation. The macro’s parameters allow for control over the generated reference’s format and the type of output produced.

Usage

The config_ref macro is used in an AsciiDoc document as follows:

config_ref:configRef,isLink,path[]

The config_ref macro takes three parameters:

configRef: This is the configuration reference, which is also used to generate the anchor link if isLink is true.
isLink: Whether the output should be a link. If isLink is set to true, the output will be a cross-reference (xref) to the relevant configuration value.
path: This is the path to the document where the configuration value is defined. This parameter is used to to generate the link if isLink is true.

❗	The path must be the name of a document at the root of the `reference` module.

📎

The config_ref macro is environment-aware. It checks if the document it is being used in is part of a Kubernetes environment by checking if the env-kubernetes attribute is set in the document’s attributes. Depending on this check, it either prepends storage.tieredConfig. to the configRef or just uses the configRef as is.

For example:

config_ref:example_config,true,tunable-properties[]

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'

glossterm

The glossterm inline macro provides a way to define and reference glossary terms in your AsciiDoc documents.

📎	This macro is a customized version of `asciidoctor-glossary`.

Usage

Use the glossterm inline macro to reference a term within the text of the document:

glossterm:my term[myDefinition]

It takes two parameters:

term: The term to be defined.
definition (optional): The definition of the term. If the term is defined in the shared component or the local-terms object of the antora.yml file, you can omit the definition as it will always be replaced by those definitions.

Configuration options

glossary-log-terms (optional)

Whether to log a textual representation of a definition list item to the console.

glossary-term-role (optional)

Role to assign each term. By default, glossary terms are assigned the glossary-term role, which gives them the class glossary-term in generated html.

glossary-links (optional)

Whether to generate links to glossary entries. By default, links to the glossary entries are generated from the glossary terms. To avoid this, set the attribute to false as either asciidoctor configuration or a header attribute.

glossary-page (optional)

Target page for glossary links. By default, links are generated to the same page as the glossary term. To specify the target page, set this attribute to the resource ID of a page where the glossary block macro is used.

glossary-tooltip (optional)

Whether to enable tooltips for the defined terms. Valid values are:

title: This uses the browser built-in title attribute to display the definition.
true: This inserts the definition as the value of the attribute data-glossary-tooltip.
data-<attribute-name>: This inserts the definition as the value of the supplied attribute name, which must start with data.

The last two options are intended to support js/css tooltip solutions such as tippy.js.

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'

helm_ref

This is an inline macro to create links to a Helm values.yaml file on ArtifactHub.

Usage

In an AsciiDoc document, use the helm_ref macro as follows:

helm_ref:<helmRef>[]

Where <helmRef> is the Helm configuration value you want to reference in the values.yaml file.

For example:

Given a Helm reference value of myConfigValue, you would use the macro like this:

helm_ref:myConfigValue[]

This will generate the following output:

For default values and documentation for configuration options, see the https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=myConfigValue[values.yaml] file.

If you do not specify a Helm reference value, the macro generates a link without specifying a path.

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'

components_by_category

This macro generates a tabbed interface to display Redpanda Connect components by category.

The categories are fetched from the connectCategoriesData that’s generated in the Component category aggregator extension.

Usage

components_by_category::[<type>]

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'

component_table

This macro generates a searchable table of all Redpanda Connect components with filters for support and type.

The types are fetched from the flatComponentsData that’s generated in the Component category aggregator extension.

Usage

component_table::[]

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'

component_type_dropdown

This macro generates a dropdown of other supported types for a particular component, allowing users to switch between different types.

The types are fetched from the flatComponentsData that’s generated in the Component category aggregator extension.

Usage

component_type_dropdown::[]

Registration example

asciidoc:
  extensions:
    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'

Development quickstart

This section provides information on how to develop this project.

Prerequisites

To build this project, you need the following software installed on your computer:

git (command: git)
Node.js (commands: node, npm, and npx)

git

Make sure you have git installed.

git --version

If not, download and install the git package for your system.

Node.js

Make sure that you have Node.js installed (which also provides npm and npx).

node --version

If this command fails with an error, you don’t have Node.js installed.

Now that you have git and Node.js installed, you’re ready to start developing on this project.

Clone the project

Clone the project using git:

git clone https://github.com/redpanda-data/docs-extensions-and-macros

Change into the project directory and stay in this directory when running all subsequent commands.

Install dependencies

Use npm to install the project’s dependencies inside the project. In your terminal, run the following command:

npm ci

This command installs the dependencies listed in package-lock.json into the node_modules/ directory inside the project. This directory should not be committed to the source control repository.

Use your local project

If you want to use the project locally before it is published, you can specify the path to the extensions in the local-antora-playbook.yml file.

asciidoc:
  attributes:
  extensions:
  - '<path-to-local-project>/docs-extensions-and-macros/extensions/<extension-name>'

Name		Name	Last commit message	Last commit date
Latest commit History 203 Commits
.github/workflows		.github/workflows
asciidoc-extensions		asciidoc-extensions
extensions		extensions
macros		macros
preview		preview
.gitignore		.gitignore
.npmignore		.npmignore
README.adoc		README.adoc
local-antora-playbook.yml		local-antora-playbook.yml
package-lock.json		package-lock.json
package.json		package.json

redpanda-data/docs-extensions-and-macros

Folders and files

Latest commit

History

Repository files navigation

Antora Extensions and Macros for Redpanda Docs

Prerequisites

Antora Extensions

Add Bloblang samples to pages

Environment variables

Configuration options

Example Bloblang YAML file

Add pages to root

Environment variables

Configuration options

Registration example

Algolia indexer

Environment variables

Configuration options

Registration example

Archive attachments

Environment variables

Configuration options

Example configuration

Behavior with multiple components/versions

Component category aggregator

Environment variables

Configuration options

Registration example

Generate index data

Environment variables

Configuration options

Example configuration

Use the generated data

Redpanda Connect tag modifier

Environment variables

Configuration options

Registration Example

Version fetcher

Environment variables

Registration example

Validate attributes

Environment variables

Configuration options

Registration example

Related docs

Environment variables

Configuration options

Registration example

Related labs

Environment variables

Configuration options

Registration example

Global attributes

Environment variables

Configuration options

Registration example

Produce redirects (customization of core Antora)

Environment variables

Configuration options

Registration example

Replace attributes in attachments

Environment variables

Configuration options

Registration Example

Aggregate terms

Environment variables

Configuration options

Registration example

Unlisted pages

Environment variables

Configuration options

Registration example

Asciidoc Extensions

Add line numbers and highlights

Registration example

Macros

config_ref

Usage

Registration example

Packages