Skip to content

fix(docs): use MDX comments in recipe-health.md so Fern publish parses#1365

Merged
mchmarny merged 1 commit into
mainfrom
fix/fern-mdx-recipe-health-comments
Jun 15, 2026
Merged

fix(docs): use MDX comments in recipe-health.md so Fern publish parses#1365
mchmarny merged 1 commit into
mainfrom
fix/fern-mdx-recipe-health-comments

Conversation

@mchmarny

Copy link
Copy Markdown
Member

Summary

Convert the HTML comments in docs/user/recipe-health.md to MDX comment syntax so the Publish Fern Docs workflow can parse the page.

Motivation / Context

Fern parses docs as MDX, which rejects HTML comments (<\!-- -->). recipe-health.md is in the Fern nav (docs/index.yml) and carried the Apache license header plus the BEGIN/END AICR-HEALTH splice markers as HTML comments, breaking the publish job:

Failed to parse ../docs/user/recipe-health.md: Unexpected character `\!` (U+0021) before name ...

(container-images.md has the same license header but is not in the nav, so it is never MDX-parsed — only this file broke.)

Fixes: N/A
Related: https://github.com/NVIDIA/aicr/actions/runs/27553892737/job/81447404791

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
  • Build/CI/tooling

Component(s) Affected

  • Docs/examples (docs/, examples/)
  • Other: Makefile (recipe-health-docs splice target)

Implementation Notes

  • docs/user/recipe-health.md: license header + both AICR-HEALTH splice markers converted from <\!-- ... --> to {/* ... */}.
  • Makefile (recipe-health-docs): splice guard now uses grep -qF and the awk splice uses index($0, ...) (fixed-string match) to avoid regex-escaping the {, *, /, } metacharacters in the new markers.

Testing

make recipe-health-docs   # re-splices idempotently
git diff docs/user/recipe-health.md   # only the 4 comment lines differ; 37-recipe table body untouched

Risk Assessment

  • Low — Isolated docs + build-tooling change, easy to revert.

Rollout notes: N/A

Checklist

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

@mchmarny mchmarny requested a review from a team as a code owner June 15, 2026 14:44
@mchmarny mchmarny added the theme/ci-dx CI pipelines, developer experience, and build tooling label Jun 15, 2026
@mchmarny mchmarny self-assigned this Jun 15, 2026
@mchmarny mchmarny enabled auto-merge (squash) June 15, 2026 14:46
@coderabbitai

coderabbitai Bot commented Jun 15, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 38d4fad9-cd8c-4d46-af52-343334faa47e

📥 Commits

Reviewing files that changed from the base of the PR and between ed12037 and 327e927.

📒 Files selected for processing (4)
  • Makefile
  • docs/design/009-recipe-health-tracking.md
  • docs/user/recipe-health.md
  • tools/health/main_test.go

📝 Walkthrough

Walkthrough

The PR updates the comment syntax used for AICR-HEALTH section delimiters and the license header in docs/user/recipe-health.md from HTML comment syntax (<!-- -->) to JSX/JavaScript-style comment syntax ({/* */}). Correspondingly, the recipe-health-docs Makefile target is updated to detect the new marker strings during staleness validation and to use the new marker patterns in the awk splice command that regenerates the auto-generated section of the document. Test validation and design documentation are also updated to reflect the new marker format.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

  • NVIDIA/aicr#1317: Modifies the same Makefile recipe-health-docs target and docs/user/recipe-health.md AICR-HEALTH marker/sentinel region splicing logic that this PR updates.
  • NVIDIA/aicr#1304: Introduced the original recipe-health-docs target and marker-based splicing plumbing that this PR updates to use the new MDX comment syntax.
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: converting HTML comments to MDX comment syntax in recipe-health.md to fix Fern doc parsing.
Description check ✅ Passed The description is comprehensive and directly related to the changeset, explaining the motivation (Fern parsing issue), implementation details, testing approach, and risk assessment.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/fern-mdx-recipe-health-comments

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/user/recipe-health.md (1)

34-82: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Update marker-contract consumers to match Line 34 and Line 82.

The new {/* ... */} markers here are correct for Fern/MDX, but tools/health/main_test.go still hard-codes <!-- BEGIN/END AICR-HEALTH -->; that guard test will fail until updated. Please also align docs/design/009-recipe-health-tracking.md so contributor-facing docs describe the current marker contract.

Proposed follow-up patch
diff --git a/tools/health/main_test.go b/tools/health/main_test.go
@@
-    for _, marker := range []string{"<!-- BEGIN AICR-HEALTH -->", "<!-- END AICR-HEALTH -->"} {
+    for _, marker := range []string{"{/* BEGIN AICR-HEALTH */}", "{/* END AICR-HEALTH */}"} {
         if !strings.Contains(string(data), marker) {
             t.Errorf("%s is missing splice marker %q", docPath, marker)
         }
     }

diff --git a/docs/design/009-recipe-health-tracking.md b/docs/design/009-recipe-health-tracking.md
@@
-...between `<!-- BEGIN AICR-HEALTH -->` / `<!-- END AICR-HEALTH -->`.
+...between `{/* BEGIN AICR-HEALTH */}` / `{/* END AICR-HEALTH */}`.
🤖 Prompt for 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.

In `@docs/user/recipe-health.md` around lines 34 - 82, The markers in the
recipe-health.md file have been updated from HTML comments (<!-- BEGIN/END
AICR-HEALTH -->) to JSX/MDX comments ({/* BEGIN AICR-HEALTH */}), but this
change needs to be reflected in the marker-contract consumers. Update
tools/health/main_test.go to search for the new JSX/MDX marker format instead of
the old HTML comment syntax to ensure the guard test passes with the updated
markers. Also update docs/design/009-recipe-health-tracking.md to document the
new marker format so that contributor-facing documentation accurately describes
the current marker contract.
🤖 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.

Outside diff comments:
In `@docs/user/recipe-health.md`:
- Around line 34-82: The markers in the recipe-health.md file have been updated
from HTML comments (<!-- BEGIN/END AICR-HEALTH -->) to JSX/MDX comments ({/*
BEGIN AICR-HEALTH */}), but this change needs to be reflected in the
marker-contract consumers. Update tools/health/main_test.go to search for the
new JSX/MDX marker format instead of the old HTML comment syntax to ensure the
guard test passes with the updated markers. Also update
docs/design/009-recipe-health-tracking.md to document the new marker format so
that contributor-facing documentation accurately describes the current marker
contract.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 153c3dcf-326b-48ee-8ba7-28f9e3b36b8e

📥 Commits

Reviewing files that changed from the base of the PR and between 97934ad and ed12037.

📒 Files selected for processing (2)
  • Makefile
  • docs/user/recipe-health.md

@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Coverage Report ✅

Metric Value
Coverage 77.1%
Threshold 75%
Status Pass
Coverage Badge
![Coverage](https://img.shields.io/badge/coverage-77.1%25-green)

No Go source files changed in this PR.

Fern parses docs as MDX, which rejects HTML comments (`<\!-- -->`).
recipe-health.md is in the Fern nav (docs/index.yml) and carried the
Apache license header plus BEGIN/END AICR-HEALTH splice markers as HTML
comments, breaking `Publish Fern Docs`. Convert all three to MDX comment
syntax `{/* ... */}` and update the make recipe-health-docs splice
guard/awk to match (fixed-string grep + index() to avoid regex-escaping
the brace/star metacharacters). Splice remains idempotent.

Also update the marker-presence test (tools/health) and ADR-009 to the
new MDX markers.
@mchmarny mchmarny force-pushed the fix/fern-mdx-recipe-health-comments branch from ed12037 to 327e927 Compare June 15, 2026 14:56
@mchmarny mchmarny requested a review from a team as a code owner June 15, 2026 14:56

@ArangoGutierrez ArangoGutierrez left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed at 327e927 — clean fix, no objection.

HTML-comment to MDX-comment conversion so the Fern publish job can parse recipe-health.md, with the matching Makefile splice update and the tools/health test. The grep -qF / awk index($0, ...) switch to fixed-string matching is the right call, since the new markers contain regex metacharacters ({, *, /, }).

Confirmed the marker migration is complete: a repo-wide search shows only four files reference the AICR-HEALTH markers and all four are updated here, and recipe-health-check does not grep the markers (so it is unaffected). Fern Check is green.

No impact to the release artifacts — the only Go change is the expected-marker strings in tools/health's test, and tools/health is a go run docs-generation tool, not part of the shipped binaries or images.

This approval satisfies the aicr-maintainer code-owner review for the maintainer-owned paths here (Makefile, tools/health/**). The docs/** files are under aicr-write and still need an approval from that team (not the author). The merge gate will also hold until the in-flight CI checks finish green.

@mchmarny mchmarny merged commit de2d9dd into main Jun 15, 2026
33 checks passed
@mchmarny mchmarny deleted the fix/fern-mdx-recipe-health-comments branch June 15, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs size/S theme/ci-dx CI pipelines, developer experience, and build tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants