AsciiDoc Patterns

AsciiDoc patterns I’ve actually used. Every entry has a date and context.

2026-03-22: MathJax stem:[] Bracket Escaping

Problem: MathJax error "Could not find closing ']'" when rendering fractional exponents in college algebra docs

Context: College algebra documentation, stem:[] inline math

The Fix:

// WRONG — AsciiDoc parses [n] as attribute
stem:[\sqrt[n]{a}]

// RIGHT — escape both brackets
stem:[\sqrt\[n\]{a}]

Rule: In inline \$...\$, always escape nth root brackets: \sqrt\[n\]. AsciiDoc’s bracket parser conflicts with LaTeX.

Worklog: WRKLOG-2026-03-22

2026-02-26: Attribute Verification Before Writing

Problem: 6 missing attributes caused broken doc rendering — used attributes that didn’t exist in antora.yml

Context: Writing infrastructure documentation, assumed attribute names existed without checking

The Fix:

# ALWAYS verify attribute exists before using it
grep -i "wazuh" docs/antora.yml

# If attribute doesn't exist: ADD IT FIRST
# Edit antora.yml, then use in document

# Build and verify before commit
make 2>&1 | grep -E "WARN|ERROR"

Rule: NEVER assume an attribute exists. ALWAYS grep antora.yml first. If {some-attribute} isn’t defined, the page renders the literal {some-attribute} text.

Worklog: WRKLOG-2026-02-26

2026-04-04: npm install Required on Fresh Clones

Problem: make failed with "Cannot find module '@antora/lunr-extension'" on P16g

Context: Fresh clone of domus-docs on P16g — node_modules/ is gitignored (correctly)

The Fix:

# After cloning any Antora repo with extensions
cd ~/domus-docs
npm install

# Then build works
make

Rule: node_modules/ is gitignored. After git clone on a new machine, always npm install before make.

Worklog: WRKLOG-2026-04-04

Template for New Entries