Skip to content

Fix glossterm macro usage #1569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kbatuigas wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fix glossterm macro usage #1569

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion modules/deploy/partials/linux/bootstrap.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[bootstrapping]]
= Bootstrap broker configurations

Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the glossterm:listener[listeners], glossterm:seed-server[,seed servers], and glossterm:advertised listener[,advertised listeners], which ensure proper network connectivity and accessibility.
Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the glossterm:listener[,listeners], glossterm:seed server[,seed servers], and glossterm:advertised listener[,advertised listeners], which ensure proper network connectivity and accessibility.
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Find glossary-related files and check for term definitions
find . -type f \( -name "*glossary*" -o -name "*terms*" \) | head -20

Repository: redpanda-data/docs

Length of output: 101

🏁 Script executed:

# Search for glossterm macro usage and glossary definitions
rg -n 'glossterm:' --type=asciidoc | head -30

Repository: redpanda-data/docs

Length of output: 9401

🏁 Script executed:

# Look for glossary definition patterns (likely using [[...]] or similar)
rg -n '\[\[.*\]\]' --type=asciidoc | grep -E '(listener|seed|advertised)' | head -20

Repository: redpanda-data/docs

Length of output: 143

🌐 Web query:

AsciiDoc glossterm macro syntax comma notation

💡 Result:

In AsciiDoc / Asciidoctor, the glossterm macro is written using the inline macro “target + attribute list” form:

  • Syntax: glossterm:<term>[<definition>]
  • Example: glossterm:my term[myDefinition] (definition is optional in some implementations) [1], [2]

So the “comma notation” (i.e., macro:[a, b, c]) is not part of glossterm’s syntax; commas are generally used to separate multiple positional attributes in an attribute list for macros that define more than one positional attribute (e.g., indexterm:[primary, secondary, tertiary]) [3]. By contrast, glossterm takes the term as the target (after :) and (optionally) the definition as the first positional attribute (inside []) [1], [2].

If you’re thinking of commas because you saw them used inside other macros (e.g., kbd:[Ctrl,T]), that’s a macro-specific shorthand for that macro, not a general rule that applies to glossterm [4].

Sources: [1] (Redpanda docs-extensions-and-macros README: glossterm usage), [2] (antora-extensions-and-macros package docs: glossterm usage), [3] (Asciidoctor user manual: indexterm comma-separated positional attributes), [4] (Asciidoctor keyboard macro: comma-separated keys).

🌐 Web query:

AsciiDoc glossterm macro correct syntax example

💡 Result:

glossterm is not a built-in AsciiDoc/Asciidoctor macro; it’s provided by glossary extensions (e.g., antora-extensions-and-macros / redpanda-data docs-extensions-and-macros). In those extensions, the inline macro syntax is:

glossterm:my term[myDefinition]
  • target: the term (my term)
  • attribute list / positional: the definition (myDefinition, often optional if defined elsewhere) [1][2]

Minimal working example (with the matching glossary block macro used by the same extensions):

A glossterm:broker[A server that stores and serves messages] is part of the system.

glossary::[]

This collects glossterm definitions and renders them as a glossary/definition list when glossary::[] is placed later in the document [3].

Sources: [1] [2] [3]

🏁 Script executed:

# Get the glossary file and search for the terms in question
cat modules/reference/pages/glossary.adoc | head -100

Repository: redpanda-data/docs

Length of output: 267

🏁 Script executed:

# Search for the specific term definitions
rg -n -A3 '(listener|seed|advertised)' modules/reference/pages/glossary.adoc | head -50

Repository: redpanda-data/docs

Length of output: 44

🏁 Script executed:

# Search for how terms are defined in the glossary file (look for patterns like [[term]] or similar)
rg -n '^\[\[' modules/reference/pages/glossary.adoc | head -20

Repository: redpanda-data/docs

Length of output: 44

🏁 Script executed:

# Check glossary file size and structure
wc -l modules/reference/pages/glossary.adoc

Repository: redpanda-data/docs

Length of output: 102

🏁 Script executed:

# Get the full glossary file
cat modules/reference/pages/glossary.adoc

Repository: redpanda-data/docs

Length of output: 267

🏁 Script executed:

# Search for all term ID patterns in glossary
rg -n '\[\[' modules/reference/pages/glossary.adoc

Repository: redpanda-data/docs

Length of output: 44

🏁 Script executed:

# Look for inline macro definitions or term patterns
rg -n 'term::|::' modules/reference/pages/glossary.adoc | head -20

Repository: redpanda-data/docs

Length of output: 44

🏁 Script executed:

# Search for glossary or glossterm extension configuration
find . -type f \( -name "*.js" -o -name "*.json" -o -name "*.yml" -o -name "*.yaml" \) | xargs grep -l "glossterm\|glossary" 2>/dev/null | head -10

Repository: redpanda-data/docs

Length of output: 255

🏁 Script executed:

# Look for where term definitions might be stored
rg -n 'listener::|listener:' --type=asciidoc | grep -v glossterm | head -20

Repository: redpanda-data/docs

Length of output: 2141

🏁 Script executed:

# Search for antora or extension related files that might define glossterm macro behavior
find . -type f -name "*.js" -o -name "*.json" | xargs grep -l "glossterm" 2>/dev/null

Repository: redpanda-data/docs

Length of output: 227

🏁 Script executed:

# Check if there's a docs configuration that shows how glossterm works
find . -type f \( -name "antora.yml" -o -name "package.json" \) | head -5

Repository: redpanda-data/docs

Length of output: 89

🏁 Script executed:

# Check antora.yml for glossterm extension configuration
cat ./antora.yml

Repository: redpanda-data/docs

Length of output: 5750

🏁 Script executed:

# Check package.json for dependencies related to glossterm or macro extensions
cat ./package.json

Repository: redpanda-data/docs

Length of output: 1321

🏁 Script executed:

# Search for any documentation about the glossterm macro in the repo
rg -n 'glossterm' --type=asciidoc modules/ROOT/pages/ | head -20

Repository: redpanda-data/docs

Length of output: 121

🏁 Script executed:

# Check if there's a custom extension directory
find . -type d -name "extensions" -o -name "*macro*" 2>/dev/null

Repository: redpanda-data/docs

Length of output: 44

🏁 Script executed:

# Search for documentation about the docs-extensions-and-macros in the repo
rg -n 'docs-extensions-and-macros' --type=adoc --type=md | head -10

Repository: redpanda-data/docs

Length of output: 90

🏁 Script executed:

# Look for any README or documentation about the extension
find . -type f \( -name "README*" -o -name "*.md" \) | xargs grep -l "glossterm\|docs-extensions" 2>/dev/null

Repository: redpanda-data/docs

Length of output: 46

🏁 Script executed:

# Check if there's a local extensions folder
find . -type d -name "extensions" -o -type d -name "*extension*" 2>/dev/null | head -10

Repository: redpanda-data/docs

Length of output: 44

🌐 Web query:

@redpanda-data/docs-extensions-and-macros glossterm syntax documentation

💡 Result:

In @redpanda-data/docs-extensions-and-macros, the glossterm macro is an inline AsciiDoc macro with this syntax:

  • Define/reference a term (with optional definition):
    • glossterm:<term>[<definition>]
    • Example: glossterm:my term[myDefinition]
  • Parameters:
    1. term (required)
    2. definition (optional) — can be omitted if the term is already defined in the shared component or in local-terms in antora.yml. (github.com)

Related attributes (configuration options):

  • glossary-log-terms
  • glossary-term-role (default role is glossary-term)
  • glossary-links (set to false to disable links)
  • glossary-page (resource ID of the page that contains the glossary)
  • glossary-tooltip (title, true, or data-<attribute-name>) (github.com)

Citations:

Remove the comma from glossterm macro syntax.

The glossterm macros use incorrect syntax with a comma separator: glossterm:<term>[,<display>]. Per the @redpanda-data/docs-extensions-and-macros documentation, the correct syntax is glossterm:<term>[<display>] without the comma. Update the three glossterm calls on this line to remove the leading comma:

  • glossterm:listener[listeners]
  • glossterm:seed server[seed servers]
  • glossterm:advertised listener[advertised listeners]
🤖 Prompt for AI Agents 
In `@modules/deploy/partials/linux/bootstrap.adoc` at line 4, Update the three
glossterm macro usages on the line to remove the comma between the term and the
optional display text: change glossterm:listener[,listeners] to
glossterm:listener[listeners], glossterm:seed server[,seed servers] to
glossterm:seed server[seed servers], and glossterm:advertised
listener[,advertised listeners] to glossterm:advertised listener[advertised
listeners] so they follow the correct glossterm:<term>[<display>] syntax.


Starting in version 23.3.8, `rpk` enhances the bootstrapping process with additional flags for configuring advertised listener addresses directly.

Expand Down