Consolidate doc-quality checks into one workflow - #3092
Open
claude[bot] wants to merge 6 commits into
Open
Conversation
Merge validate-mdx.yml, linkcheck-pr.yml, and readability-delta.yml into .github/workflows/doc-quality.yml: one pull_request-driven runner job (job id validate-mdx, unchanged so the branch-protection required check keeps its name) and one upserted PR comment keyed by <!-- doc-quality-report -->. - MDX validation (mint validate + mint broken-links) stays blocking and keeps its npm/mint caching and script unchanged. - The lychee external-link check moves off deployment_status onto plain pull_request; since PR #3037 it reads changed files from the checkout, so the preview-deployment wait was vestigial. Deleting that code also deletes the wrong-PR resolution bug (DOCS-3041). - The readability delta keeps its submodule/pip/judge mechanics and stays informational; it still skips on fork PRs. - A single scope-gate diff fast-exits everything when a PR touches no Mintlify-relevant files. - A one-time cleanup step deletes the old lychee and readability comments from open PRs. Intentionally untouched: knowledgebase-nav.yml, mintlify-deployment-preview.yml, linkcheck-prod.yml, and the PinGuard pair.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
No preview available (2)
Updated 2026-08-21 01:17:05 UTC for deployment · 010aeea. |
Replace the Readability delta section with a Doc quality section covering the consolidated workflow (blocking MDX validation plus informational external-link and readability checks, job id validate-mdx), and update the downstream-check example in the App-authentication section.
Contributor
Doc quality
Updated 2026-08-21T22:44:53Z for 7067f40 |
The readability delta now runs as an informational step of .github/workflows/doc-quality.yml; update the two references to the deleted readability-delta.yml in scripts/readability.
Contributor
There was a problem hiding this comment.
Pull request overview
Consolidates three documentation-quality workflows into one required workflow with unified reporting.
Changes:
- Combines MDX validation, external-link checking, and readability reporting.
- Replaces three legacy workflows with
doc-quality.yml. - Updates workflow and readability documentation.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/doc-quality.yml |
Implements consolidated checks and reporting. |
.github/workflows/validate-mdx.yml |
Removes legacy validation workflow. |
.github/workflows/linkcheck-pr.yml |
Removes legacy link-check workflow. |
.github/workflows/readability-delta.yml |
Removes legacy readability workflow. |
.github/workflows/README.md |
Documents the consolidated workflow. |
scripts/readability/README.md |
Updates the readability workflow reference. |
scripts/readability/pr_report.py |
Updates the workflow reference in module documentation. |
Suppressed comments (1)
.github/workflows/doc-quality.yml:289
- The pip cache is part of the informational readability path, but a cache service/action failure currently fails the whole required job. Make this step non-fatal so readability infrastructure cannot block a PR.
- name: Cache pip packages
if: steps.scope.outputs.is_fork != 'true' && steps.scope.outputs.mdx_changed == 'true'
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
mdlinville
marked this pull request as ready for review
August 21, 2026 01:15
- Gate readability on any changed .mdx including deletions (mdx_changed_any), so deleted-page PRs still get the 'page removed' row; the non-deleted list keeps feeding lychee only. - Refresh a stale doc-quality comment to an all-skipped state when a later push removes every Mintlify-relevant change (update-only, never creates a comment on that path). - Raise the job timeout to 35 minutes for headroom over the two 10-minute advisory step timeouts plus checkout/mint install. - Make setup-python and the pip cache continue-on-error so readability infra outages cannot fail the required job. - Match comment author github-actions[bot] as well as the marker in the upsert, legacy-comment cleanup, and stale-refresh lookups, so contributor comments quoting a marker are never edited or deleted. - Fix the workflows README to say the workflow runs on the default pull_request activity types, not all types.
Should-fix items: - Concurrency: key the group on the PR number instead of the bare branch name, so two PRs whose heads share a name can no longer cancel each other's required check (head_ref is not unique per PR). - Report: when a blocking setup step fails, label the skipped lychee and readability rows 'Did not run (an earlier step failed)' instead of falsely claiming 'no .mdx changes' (branch on mdx_changed / mdx_changed_any in the Assemble step). - Hardening: persist-credentials: false on the checkout — nothing needs the persisted token (diffs are local, the submodule step brings DOCENGINE_TOKEN, gh steps get the token via env), so unpinned mint/lychee code no longer runs next to a write-capable token in .git/config. - Regex duplication: point validate-mdx-mintlify.sh's header at doc-quality.yml (was the deleted validate-mdx.yml) and add a matching keep-in-sync note next to the workflow's scope-gate grep. Lower-risk correctness: - Upsert: set -euo pipefail and capture the comment listing before head -n1, so a transient gh failure fails the (continue-on-error) step instead of falling through to create a permanent duplicate comment. Same discipline in the refresh-stale step. - Validation excerpt: size the code fence one backtick longer than the longest backtick run in the excerpt, so mint output quoting .mdx code fences cannot close the block early and swallow </details>. - Deleted-fork PRs: treat a head.repo.fork value that is not exactly 'false' (renders empty when head.repo is null) as a fork, so the report goes to the step summary instead of 403ing comment steps. Maintainability: - Legacy-comment cleanup: skip PRs opened after 2026-10-01 so the per-push paginated listings self-retire as pre-consolidation PRs drain. - Scope gate: one --name-status diff now feeds both the non-deleted .mdx input list and the includes-deletions readability gate (was two near-identical diffs). - README: document that workflow_dispatch no longer offers the old linkcheck-pr.yml full-tree external-link sweep (linkcheck-prod.yml is the closest substitute). - Stale comments: build-css.yml and calibreapp-image-actions.yml now cite 'Doc quality' instead of the deleted 'Validate MDX'; the SC2140 note no longer implies readability-delta.yml still exists. - pr_report.py: flag --include-marker and REPORT_MARKER as legacy / manual-use-only, warning that the cleanup step deletes bot comments carrying that marker. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GzG5FNbFp5dZLmjdjir52j
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Matt Linville · Slack thread
Description
Merges the three checkout-based PR doc-quality workflows into a single
pull_request-driven workflow with one runner job and one sticky PR comment.Before: 3 workflows (
validate-mdx.yml,linkcheck-pr.yml,readability-delta.yml), 5 runner-jobs and 3 bot comments per push on a typical.mdxPR, with the external link check driven bydeployment_statusevents and carrying the wrong-PR-resolution bug DOCS-3041.After: one
pull_request-driven Doc quality workflow whose job id staysvalidate-mdx, so the branch-protection required check keeps its name with no unprotected window. That gets a typical push down to 2 runner-jobs (doc-quality + the PinGuard twin) and 2 PR comments (Mintlify's own comment with the merged preview-links block, plus one doc-quality comment). Thedeployment_status/PR-resolution code — including the DOCS-3041 bug — is deleted outright.How it works
git diffagainst the merge-base decides everything. Nopaths:filter on the trigger (required-check safety); a PR with no Mintlify-relevant changes passes in seconds without installing anything.mint validate+mint broken-links, unchanged script and npm/mint caching) is the only step that can fail the job. The lychee external-link check (changed.mdxonly, samelychee.toml/args as before) and the readability delta (same submodule/pip/LLM-judge mechanics as before) are informational.<!-- doc-quality-report -->: a status table up top, with validation errors, the lychee report, and the readability table in collapsed<details>sections (each capped at 15k chars).<!-- lychee-link-checker-comment -->and<!-- readability-delta-report -->comments left by the old workflows on open PRs.Intentionally untouched:
knowledgebase-nav.yml,mintlify-deployment-preview.yml(the only genuinely preview-dependent workflow),linkcheck-prod.yml, and the PinGuard pair.Testing
actionlint(with shellcheck) passes on the new workflowvalidate-mdxcheckRelated issues
deployment_statusPR-resolution code)