ci: limit blog Markdown link checks to newly added posts

[MFA-G]

Fixes #1344.

The problem

markdown-link-check-md and markdown-link-check walk the repository root, so every run checks all 24 posts in blog/. Those posts are point-in-time announcements — kubecon-na-2023.md, the monthly fine-grained-news-* roundups — and their external links rot on their own schedule. When one does, the failure lands on whatever unrelated PR happens to run next, which is what prompted the request in #1341.

The change

Blog posts are checked when a PR adds them, and not otherwise.

• The two existing jobs are scoped with folder-path: 'docs', so they no longer descend into blog/.
• markdown-link-check-root keeps the root README.md covered — folder-path: docs would otherwise drop it, so it gets max-depth: 1.
• markdown-link-check-new-blog-posts runs scripts/new-blog-posts.mjs to list the posts the branch adds and, only when there are some, runs markdown-link-check over exactly those files. Non-blog content is untouched.

scripts/new-blog-posts.mjs is deliberately small: it asks git for --diff-filter=A <base>...HEAD -- blog, then keeps blog/*.{md,mdx}. Two details are load-bearing:

• --diff-filter=A — a modification is not an addition, so editing an existing post never puts its historical links on trial.
• Three-dot <base>...HEAD — the diff is against the merge base. A two-dot diff would report posts that landed on main after the branch forked as if the branch had added them, and a stale branch would then fail on someone else's post.

Acceptance criteria

Criterion	Where
PR adding a post with a broken link fails	verified below; markdown-link-check exits 123
PR editing an existing post skips its historical links	reports nothing when the branch only edits an existing post
PR with no new posts runs no blog check	if: steps.new-posts.outputs.files != '', plus reports nothing for a branch that touches no blog posts
Works in PR and preview CI	reads github.base_ref; preview.yml is a separate workflow and is unchanged
Automated coverage for added and existing cases	scripts/new-blog-posts.test.mjs, 11 tests

Validation

Tests use node:test (no new dependency) and drive a real temporary git repository rather than a stubbed git, since the criteria are about what a branch produces. Added as npm test, wired into the build job.

$ npm test
# tests 11
# pass 11
# fail 0

The CLI, driven against real branches in this checkout:

--- baseline: branch adds no blog post ---
exit=0            (no output — correct)
--- branch adds a post ---
blog/zz-temp-post.md
--- --github-output ---
files=blog/zz-temp-post.md
--- branch only EDITS an existing post ---
exit=0            (no output — correct)

And the workflow's link-check step, run verbatim:

$ echo "blog/incubation-announcement.md,blog/kubecon-na-2023.md" | tr ',' '\n' | xargs \
    npx markdown-link-check --quiet --config .github/workflows/markdown.links.config.json
exit=0

# same pipeline, on a post containing a dead link:
  ERROR: 1 dead link found in /tmp/broken-post.md !
  [✖] https://openfga.dev/this-path-does-not-exist-abc123 → Status: 404
exit=123

npx eslint scripts/ and npx prettier --check are clean.

Note

markdown-link-check-new-blog-posts needs fetch-depth: 0 for the merge-base diff. If you would rather avoid the full clone, fetch-depth: 0 can be dropped in favour of an explicit git fetch --deepen — happy to switch. I also kept the root README on its own job rather than folding it into a folder-path: 'docs,.' list, because . would re-include blog/; if you would prefer a different split, let me know.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[linux-foundation-easycla]

• ❌ - login: @MFA-G / name: Fadhlan. The commit (0ab9af7) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please visit our EasyCLA portal and chat with our support bot.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Siddhant-K-code]

@MFA-G, Can you sign the CLA