Skip to content

Fix Markdown Link Check workflow and broken doc links - #28

Merged
Pnwcomputers merged 4 commits into
mainfrom
fix/v3.1-release-ci
Nov 19, 2026
Merged

Pnwcomputers merged 4 commits into
mainfrom
fix/v3.1-release-ci

Conversation

@Pnwcomputers

@Pnwcomputers Pnwcomputers commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

What's wrong

  • Markdown Link Check has failed on every run since August. actions/setup-node was set to cache: 'npm', but the repo has no package-lock.json, so the setup step fails before any link gets checked.
  • docs/TROUBLESHOOTING.md links to ../../issues. On GitHub that resolves under /blob/ and returns a 404.
  • The Commit Message Format link in the CONTRIBUTING table of contents is dead. The heading's 🏷️ emoji has an invisible U+FE0F variation selector, so GitHub's anchor is #️-commit-message-format, not #-commit-message-format.

Changes

  • md-link-check.yml: removed the npm cache, updated actions/checkout v3 → v7 and Node 20 → 22, pinned markdown-link-check@3.15.0, added a 10-minute job timeout, and made the workflow run when its own file or its config changes (plus workflow_dispatch).
  • .markdown-link-check.json (new; un-ignored in .gitignore, which ignores *.json): 20s per-link timeout, retry on 429 with a 10s fallback delay, and 403 accepted from download sites that block CI runners as bots.
  • docs/TROUBLESHOOTING.md: the Issues link now uses the full URL.
  • .github/CONTRIBUTING.md: removed U+FE0F from the heading, so GitHub's anchor matches the TOC link.
  • CHANGELOG.md: listed under 3.1. The v3.1 tag will be moved to this merge commit.

Review

Ultrareview found three things: the CONTRIBUTING anchor, no config for bot-blocking hosts, and no job timeout with --retry. All three are fixed here.

Testing

  • Markdown Link Check passes on this branch, the first green run since August.
  • GitHub's rendered CONTRIBUTING page now has the anchor -commit-message-format, which matches the TOC link.
  • Checked every relative link and all 16 external Markdown links locally: all resolve.

🤖 Generated with Claude Code

Pnwcomputers and others added 2 commits November 18, 2026 21:03
setup-node's cache: 'npm' failed every run because the repo has no
package-lock.json. Drop the cache, update checkout to v7 and Node to 22,
retry on 429s, and run the check when the workflow itself changes.

docs/TROUBLESHOOTING.md linked ../../issues, which resolves under /blob/
on GitHub and 404s; use the absolute Issues URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
v3.1 was retagged at e82b3b1, which doesn't include this fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
system-tester Ready Ready Preview Nov 19, 2026 5:10am UTC

- CONTRIBUTING: drop the U+FE0F variation selector from the Commit
  Message Format heading so GitHub's anchor matches the TOC link.
- md-link-check: add a 10-minute job timeout, pin markdown-link-check
  to 3.15.0, and add .markdown-link-check.json (20s per-link timeout,
  retry on 429 with a 10s fallback delay, accept 403 from bot-blocking
  download sites).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
.gitignore ignores *.json, so .markdown-link-check.json never got
committed and the job failed with 'Config file not accessible'. Add an
exception for it.

v3.1 will be retagged to include these fixes, so move their CHANGELOG
entries from Unreleased into the 3.1 section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Pnwcomputers Pnwcomputers changed the title Fix Markdown Link Check workflow and broken Issues link Fix Markdown Link Check workflow and broken doc links Nov 19, 2026
@Pnwcomputers
Pnwcomputers merged commit c7872b9 into main Nov 19, 2026
4 checks passed
@Pnwcomputers
Pnwcomputers deleted the fix/v3.1-release-ci branch November 19, 2026 05:11

This branch was successfully deployed

1 active deployment
Preview — ad272ca5 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant