fix(docs): catch bare <word> tags in MDX safety check by pedjak · Pull Request #1170 · NVIDIA/aicr

pedjak · 2026-06-03T14:26:04Z

Summary

Add a bare <word> angle-bracket check (check 5) to tools/check-docs-mdx and fix two cross-line inline code spans that escaped detection.

Motivation / Context

Fern's MDX parser interprets bare <word> placeholders as JSX component tags and fails with parse errors. The existing MDX safety script had no check for this pattern class.

Fixes: #1147
Related: #1151

Type of Change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Refactoring (no functional changes)
Build/CI/tooling

Component(s) Affected

CLI (cmd/aicr, pkg/cli)
API server (cmd/aicrd, pkg/server)
Recipe engine / data (pkg/recipe)
Bundlers (pkg/bundler, pkg/component/*)
Collectors / snapshotter (pkg/collector, pkg/snapshotter)
Validator (pkg/validator)
Core libraries (pkg/errors, pkg/k8s)
Docs/examples (docs/, examples/)
Other: tools/check-docs-mdx

Implementation Notes

Check 5 matches <[a-zA-Z] after stripping inline code and backslash-escaped patterns (\<word\>), excluding void HTML elements (check 1) and autolinks (check 4).
Two cross-line backtick spans in validator.md and collector.md were collapsed to single-line spans so the per-line gsub stripper correctly excludes them.

Testing

bash tools/check-docs-mdx  # OK: all doc files are MDX-safe

Script passes clean on all docs
Deliberate bare <placeholder> correctly flagged
Backtick-wrapped, code-fenced, and \<escaped\> patterns not flagged

Risk Assessment

Low — Isolated change, well-tested, easy to revert

Rollout notes: N/A

Checklist

Tests pass locally (make test with -race)
Linter passes (make lint)
I did not skip/disable tests to make CI green
I added/updated tests for new functionality
I updated docs if user-facing behavior changed
Changes follow existing patterns in the codebase
Commits are cryptographically signed (git commit -S) — GPG signing info

Add check 5 to tools/check-docs-mdx for bare angle-bracket placeholders (<name>, <phase>, etc.) that break Fern's MDX parser. Strip backslash-escaped patterns (\<word\>) to avoid false positives. Collapse cross-line inline code spans in validator.md and collector.md so the per-line backtick stripper correctly excludes them. Fixes NVIDIA#1147

copy-pr-bot · 2026-06-03T14:26:11Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

github-actions · 2026-06-03T14:26:25Z

Welcome to AICR, @pedjak! Thanks for your first pull request.

Before review, please ensure:

All commits are signed off per the DCO
CI checks pass (tests, lint, security scan)
The PR description explains the why behind your changes

A maintainer will review this soon.

coderabbitai · 2026-06-03T14:31:41Z

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 32c90752-5fd2-43a3-baaf-d20380a43654

📥 Commits

Reviewing files that changed from the base of the PR and between c97ca83 and 9b216a3.

📒 Files selected for processing (1)

docs/contributor/validator.md

📝 Walkthrough

Walkthrough

This PR extends the MDX safety lint tool to detect bare angle-bracket placeholders (<word>) outside fenced/inline code by stripping backslash-escaped angle tokens before scanning and flagging unescaped instances (excluding void HTML elements and autolinks). It also reforms two contributor docs examples: wraps a snapshotter wiring snippet in collector.md and places the Chainsaw health-check command on one line in validator.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

NVIDIA/aicr#1151: Both PRs modify tools/check-docs-mdx to extend MDX angle-bracket/placeholder safety scanning and touch contributor docs.

Suggested labels

bug

Suggested reviewers

lockwobr

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a check for bare angle-bracket placeholders in the MDX safety linting tool.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the motivation, implementation details, testing, and risk assessment for the MDX safety check enhancement.
Linked Issues check	✅ Passed	The PR implements all primary coding requirements from issue `#1147`: expanding MDX check scope to docs/contributor/, detecting bare patterns, fixing cross-line code spans, and validating the implementation works correctly [`#1147`, `#1151`].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the PR objectives: tooling enhancement in check-docs-mdx and documentation formatting fixes in validator.md and collector.md to address the MDX parser requirements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mchmarny

Welcome to AICR, @pedjak — thanks for picking this up. The fix is well-scoped: check 5 follows the same shape as the existing check 4, the backslash-escape strip is the right complement to the inline-code strip, and the two cross-line backtick spans in validator.md / collector.md are exactly the kind of collateral fix that has to land in the same PR (the per-line gsub stripper can't see across lines).

Verified locally that the script still passes clean on all docs and correctly flags a bare <word> while leaving \<word\> and `<word>` alone.

Two low-priority observations inline — both about edge cases the predicate doesn't cover (lines with mixed content, and non-void HTML containers like <details>). Neither blocks merge; flagged for future iteration. PR is behind main, so a rebase + force-push will be needed before merge, and CI requires NVIDIA-runner vetting for a first-time contributor.

LGTM.

mchmarny · 2026-06-03T20:39:09Z

+      # Bare angle-bracket placeholders: <word> that are not void HTML
+      # elements (check 1) or autolinks (check 4). MDX interprets these
+      # as JSX component tags.
+      line ~ /<[a-zA-Z]/ && line !~ /<(img|br|hr|input|source|meta|link|area|base|col|embed|param|track|wbr)([ \t>\/])/ && line !~ /<https?:\/\// {


nit: line-level negation means a line containing both a void element (or autolink) and a bare <word> won't flag the placeholder. Reproduced:

$ echo '<br /> and <foo>' > t.md && bash tools/check-docs-mdx /path/with/t.md OK

The void-element regex matches anywhere on the line, suppressing the whole line. Same shape as check 4 (autolinks), so this is consistent with existing code — flagging as an observation, not a request to change. If you wanted positional accuracy you'd strip the void/autolink matches from line (like inline code spans are stripped on lines 67/70) before the bare-tag predicate.

Actually, this is a blocker, the project docs generator will fail until this is resolved. Otherwise this LGTM

mchmarny · 2026-06-03T20:39:11Z

+      # Bare angle-bracket placeholders: <word> that are not void HTML
+      # elements (check 1) or autolinks (check 4). MDX interprets these
+      # as JSX component tags.
+      line ~ /<[a-zA-Z]/ && line !~ /<(img|br|hr|input|source|meta|link|area|base|col|embed|param|track|wbr)([ \t>\/])/ && line !~ /<https?:\/\// {


nit: the safe-list is HTML void elements only, but valid non-void containers like <details>, <summary>, <kbd>, <sub>, <sup> will get flagged if anyone uses them outside backticks. MDX accepts those fine. Quick repro:

$ echo '<details>' > t.md && bash tools/check-docs-mdx /path/with/t.md MDX: bare <word> tag outside code fence: ...:1: <details>

No doc currently triggers this (the one <details> reference in docs/contributor/maintaining.md:99 is inside backticks), so this is latent. Worth keeping in mind if someone later adds a collapsible <details> block — they'll get flagged and may not realize the fix is to escape with <...> or wrap in backticks.

github-actions · 2026-06-03T20:49:28Z

🌿 Preview your docs: https://nvidia-preview-fix-1147-mdx-bare-angle-brackets.docs.buildwithfern.com/aicr

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/contributor/validator.md`:
- Around line 215-216: The new section uses the acronyms "CI" and "OCI" without
defining them; update the first occurrence(s) (for example in the heading or
opening sentence around "What CI publishes:") to expand them like "continuous
integration (CI)" and "Open Container Initiative (OCI)" so both acronyms are
defined on first use (also apply the same expansion where CI/OCI first appear
later in the doc).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 32c90752-5fd2-43a3-baaf-d20380a43654

📥 Commits

Reviewing files that changed from the base of the PR and between c97ca83 and 9b216a3.

📒 Files selected for processing (1)

docs/contributor/validator.md

The bare <word> tag check added in #1170 reads files line-by-line and strips paired backticks within a single line. A multi-line code span that wrapped `--set-json gpu-operator:nodeSelector=<object>` across two lines left `<object>` outside the stripped backtick span on the second line, where MDX would parse it as a JSX component tag. Rewrap so the code span sits on one line. Pure text reflow; no anchor or link changes.

pedjak requested a review from a team as a code owner June 3, 2026 14:26

github-actions Bot added area/docs size/S labels Jun 3, 2026

mchmarny approved these changes Jun 3, 2026

View reviewed changes

mchmarny assigned pedjak Jun 3, 2026

Merge branch 'main' into fix/1147-mdx-bare-angle-brackets

9b216a3

mchmarny enabled auto-merge (squash) June 3, 2026 21:04

coderabbitai Bot reviewed Jun 3, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

mchmarny self-requested a review June 3, 2026 21:13

mchmarny merged commit 4e86524 into NVIDIA:main Jun 3, 2026
25 of 27 checks passed

Uh oh!

Conversation

pedjak commented Jun 3, 2026

Summary

Motivation / Context

Type of Change

Component(s) Affected

Implementation Notes

Testing

Risk Assessment

Checklist

Uh oh!

copy-pr-bot Bot commented Jun 3, 2026

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

coderabbitai Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

mchmarny left a comment

Choose a reason for hiding this comment

Uh oh!

mchmarny Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

mchmarny Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

mchmarny Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Jun 3, 2026 •

edited

Loading