Skip to content

fix(docs): correct dist/docs/3.0.1 snapshot relative path + SKILL.md MDX bare brace#3428

Merged
bokelley merged 1 commit into
mainfrom
claude/issue-3425-fix-snapshot-broken-link
Apr 28, 2026
Merged

fix(docs): correct dist/docs/3.0.1 snapshot relative path + SKILL.md MDX bare brace#3428
bokelley merged 1 commit into
mainfrom
claude/issue-3425-fix-snapshot-broken-link

Conversation

@bokelley

@bokelley bokelley commented Apr 28, 2026

Copy link
Copy Markdown
Contributor

Closes #3425

Summary

Two fixes for the CI-blocking broken-links check failures on main:

  1. Snapshot path depth (dist/docs/3.0.1/contributing/storyboard-authoring.md): The relative link to static/compliance/source/test-kits/substitution-observer-runner.yaml used ../../ (correct in the source at docs/contributing/, which is 2 levels from repo root) but the dist snapshot nests 4 levels deep (dist/docs/3.0.1/contributing/). Fixed to ../../../../static/…. This is the primary CI blocker — the broken-links workflow triggers on any dist/docs/** path change and mintlify broken-links traverses the snapshot.

  2. MDX bare brace (skills/call-adcp-agent/SKILL.md): {account_id, brand, operator, …} in the symptom table was not wrapped in backticks, causing acorn "Could not parse expression" when the MDX pipeline encounters it. Wrapped with backticks (consistent with adjacent rows using `{amount, currency}` and `{agent_url, id}`). Note: skills/ is not currently in the broken-links workflow's path triggers; this surfaced in a local mintlify broken-links run — included proactively.

Known follow-up (not in this PR): scripts/rewrite-dist-links.sh rewrites /docs/ and /schemas/ absolute paths but does not handle relative ../../static/ paths in contributing/ files. The next patch snapshot (3.0.2) will reproduce this breakage unless the script is extended or the source switches to a root-relative/absolute URL.

⚠️ Depth asymmetry — do NOT apply this fix to the source file: docs/contributing/storyboard-authoring.md is at 2 levels from repo root, so its existing ../../static/… is correct. Applying ../../../../ to the source would break the live docs site. Only the dist/ snapshot needed the deeper path.

Non-breaking justification: docs-only changes — no schema, protocol, or API surface touched. The link target file exists at the corrected path (static/compliance/source/test-kits/substitution-observer-runner.yaml).

Pre-PR review:

  • code-reviewer: approved — path arithmetic verified (4 levels correct for dist snapshot, 2 levels correct for source); MDX backtick fix consistent with adjacent table rows; noted skills/ not currently in broken-links CI scope (confirmed via .github/workflows/broken-links.yml)
  • docs-expert: approved — both fixes correct and non-breaking; confirmed source file must NOT receive the same depth change; generator gap documented as known follow-up

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_012dh24nfo6NMf42QnUi6TQQ

@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label Apr 28, 2026
@bokelley bokelley marked this pull request as ready for review April 28, 2026 15:11
@bokelley bokelley merged commit 4b3f51e into main Apr 28, 2026
15 checks passed
@bokelley bokelley deleted the claude/issue-3425-fix-snapshot-broken-link branch April 28, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

broken-links: dist/docs/3.0.1 snapshot has wrong relative path to test-kits/substitution-observer-runner.yaml

2 participants