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 2 commits into
base: main
Choose a base branch
from
Open

Fix glossterm macro usage #1569

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54b8355
Fix glossterm macro usage
kbatuigas Feb 9, 2026
e701a26
Merge branch 'main' into test-glossterm-skill
kbatuigas Feb 18, 2026
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 •
edited
Loading

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.

Copy link
Contributor

@Feediver1 Feediver1 Feb 19, 2026

Choose a reason for hiding this comment

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

I checked the output and it looks correct. In the current 25.3 content on our site, seed servers is not defined/the glssterm link does not work, so I am apt to conclude this is correct and that coderabbit might have it wrong.

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 19, 2026

Choose a reason for hiding this comment

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check how glossterm is used throughout the codebase - look for patterns with and without commas
rg -n 'glossterm:[^[]+\[,' --type=asciidoc | head -30

Length of output: 92

🏁 Script executed:

#!/bin/bash
# Also check usage without commas for comparison
rg -n 'glossterm:[^[]+\[[^,]' --type=asciidoc | head -30

Length of output: 95

🏁 Script executed:

#!/bin/bash
# Look for any documentation or examples in the repo about glossterm usage
fd -e adoc -e md README | xargs rg -l 'glossterm' 2>/dev/null

Length of output: 0

🏁 Script executed:

#!/bin/bash
# Check the actual extension package to understand the syntax better
cat package.json | jq '.dependencies."@redpanda-data/docs-extensions-and-macros"'

Length of output: 8

🏁 Script executed:

#!/bin/bash
# Check for glossterm usage with comma in the display text (fixed regex)
rg -n 'glossterm:.*\[,' --type=asciidoc | head -40

Length of output: 1742

🏁 Script executed:

#!/bin/bash
# Check for glossterm usage without comma
rg -n 'glossterm:' --type=asciidoc | grep -v '\[,' | head -40

Length of output: 11691

🏁 Script executed:

#!/bin/bash
# Get all unique glossterm patterns to understand the syntax
rg 'glossterm:[^\]]+\]' --type=asciidoc -o | sort | uniq -c | sort -rn | head -30

Length of output: 2904

🏁 Script executed:

#!/bin/bash
# Check specifically in the file being changed for context
cat modules/deploy/partials/linux/bootstrap.adoc | grep glossterm

Length of output: 355

@Feediver1, you're absolutely right, and I apologize for the incorrect review comment.

Looking at the codebase, I can see that both syntaxes are valid and actively used:

With comma (used when display text differs from the term):

  • glossterm:ACL[,access control lists (ACLs)]
  • glossterm:availability zones[,AZ]
  • The changes in this PR

Without comma (used when no alternative display is needed):

  • glossterm:Raft[]
  • glossterm:cert-manager[]
  • glossterm:Tiered Storage[]

Your PR is correctly adding commas to make the syntax consistent across all three terms on that line, not removing them. The comma separates the term identifier from the display text. My review incorrectly suggested removing the commas.

Regarding "seed servers" not being defined in production—that's a separate issue about the term definition itself, not the macro syntax.

Thank you for testing the output and catching my error!

✏️ Learnings added 
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1569
File: modules/deploy/partials/linux/bootstrap.adoc:4-4
Timestamp: 2026-02-19T19:53:57.876Z
Learning: In redpanda-data/docs-extensions-and-macros, the glossterm macro supports two valid syntaxes: `glossterm:<term>[]` when no alternative display text is needed, and `glossterm:<term>[,display text]` (with a comma) when the display text differs from the term identifier. Both patterns are used throughout the redpanda-data/docs repository.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


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

Expand Down