fix(docs): [STOPGAP] wrap two bare <token> placeholders so MDX can parse codes.mdx

[r-marques]

⚠️ STOPGAP — the real fix is nvm-monorepo#2805

codes.mdx is generated, not authored. scripts/generate-errors-doc.ts --target=docs-site in nvm-monorepo writes this whole file from libs/helpers/src/lib/output/api-errors.ts, so the next sync API errors catalogue commit reverts this PR unless the source change lands first. Caught by @eruizgar91 — see the review thread.

This PR exists only to unblock the parser in the meantime. If #2805 lands first, close this unmerged — the sync bot will produce the same two lines. Do not merge this and assume the problem is solved.

---

mintlify broken-links could not check a single page in this repo. It aborted while parsing development-guide/api-errors/codes.mdx:

erro Syntax error - Unable to parse development-guide/api-errors/codes.mdx -
    109:133-109:264: Expected a closing tag for `<token>` (109:165-109:172)
    before the end of `tableData`

Two table cells contain a bare <token> placeholder, which MDX parses as a JSX element and then fails to close:

• line 109 — Send an Authorization: Bearer <token> header …
• line 310 — Send "Authorization: Bearer <token>" matching …

The fix

Wrap both in backticks — exactly what lines 119 and 122 already do with the same placeholder, which is why those two parse fine:

-Send an Authorization: Bearer <token> header
+Send an `Authorization: Bearer <token>` header

Two lines. No wording changed beyond dropping the now-redundant straight quotes on line 310.

Verification

mintlify broken-links now runs to completion for the first time and reports success no broken links found. That is also the proof these were the only blocker — the parser previously stopped at the first bad file, so reaching "success" means every remaining page parses.

Why it went unnoticed

The check was never failing, it was not running: it died at parse time before link checking, so it never reported a broken link either way — the "green because nothing ran" shape.

Two follow-ups now handled in #2805: the generator emits its DO NOT EDIT banner only on the in-repo target, so nothing in this file says it is generated (which is exactly how this PR came to be written against the wrong repo); and a unit guard now pins that no error message/hint carries an un-backticked placeholder.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	Aug 7, 2026, 11:47 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[eruizgar91]

Reviewed the two-line MDX fix and traced where the file it patches comes from.

The diagnosis is right and the content of the fix is right — but codes.mdx is generated output, so this is applied in the wrong repository and the next catalogue sync reverts it. One HIGH inline.

Everything else checked out: lines 109 and 310 really are the only remaining bare placeholders (the other two occurrences already carry backticks), and the <a id="…"> anchors throughout are legitimate JSX, not the same bug.

Verdict: REQUEST_CHANGES — not on the change, on the repo it is applied in.

[eruizgar91]

HIGH — codes.mdx is generated, not authored. scripts/generate-errors-doc.ts --target=docs-site in nvm-monorepo writes this entire file into this repo, and both hints patched here are verbatim from its source:

• libs/helpers/src/lib/output/api-errors.ts:3308 — hint: 'Send an Authorization: Bearer <token> header or a valid Nevermined API key. …'
• libs/helpers/src/lib/output/api-errors.ts:3731 — hint: '… Send "Authorization: Bearer <token>" matching the configured scrape token.'

So the next sync reverts both lines and mintlify broken-links breaks again in exactly the same way. That sync is live practice, not hypothetical — 97a4caf7, "docs: sync API errors catalogue (nvm-monorepo@3e70243)" (#276), landed two days ago on 2026-08-05.

The trap is genuinely invisible from inside this repo: the generator emits its "Do not edit by hand — regenerate via pnpm docs:errors:generate" banner only on the in-repo target; the isMdx branch drops it. Nothing in this file says it is generated.

Fix it in api-errors.ts instead — backticks around both placeholders, dropping the now-redundant straight quotes on BCK.METRICS.0001 exactly as you did here — then run pnpm docs:errors:generate:site and let the sync produce this diff. If you want the parser unblocked before that lands, keep this PR but say in the description that it is a stopgap pending the source change, so the next sync does not silently undo it and cost someone the same debugging session twice.

[r-marques]

Confirmed — every part of this checked out, and thank you for tracing it. I verified before acting rather than taking it on faith:

• scripts/generate-errors-doc.ts + docs:errors:generate:site exist as described.
• Both hints are at exactly api-errors.ts:3308 and :3731.
• The sync is live practice — five sync API errors catalogue commits, including 97a4caf (docs: sync API errors catalogue (nvm-monorepo@3e70243) #276) and a newer 4e6452e. This would have been reverted.
• The banner really is in-repo-only: line 95 is inside the else, and the isMdx branch (77–90) has nothing.

Fixed at source in nevermined-io/nvm-monorepo#2805, which does three things:

1. The two hints, backticked exactly as here.
2. Emits the AUTO-GENERATED — DO NOT EDIT banner on the docs-site target too. Your point that the trap is invisible from inside this repo is the root cause, not a side note — leaving it means the next person repeats the same debugging session. It's an MDX comment, so it warns whoever opens the file without appearing on the rendered page.
3. A guard in api-errors-category.spec.ts asserting no message/hint carries an un-backticked angle-bracket placeholder. Mutation-tested: reverting (1) fails it naming BCK.AUTH.0002.hint and BCK.METRICS.0001.hint. Across all 511 codes it finds nothing else — which independently confirms your conclusion that lines 109 and 310 were the only two left.

Verified end to end: generated the docs-site output, dropped it into this repo, mintlify broken-links → no broken links found, the first time it has run to completion.

Taking your suggested option on this PR: keeping it as an explicitly-labelled stopgap so the parser is unblocked before the source change and the sync land, with the description updated to say so. If you'd rather just close it and wait for the bot's PR, say the word — no attachment to it.

One thing I found while there: docs/api/nvm-errors.md in nvm-monorepo is independently stale — 510 codes vs the catalogue's 511, since 00dc50ac0 landed a BCK.OAUTH code without a regeneration. Left alone in #2805 to keep it reviewable; the sync bot's PR will absorb it.