ci: Cleanup validation

[palango]

No description provided.

[palango]

@claude review

[claude]

Claude finished @palango's task in 1m 17s —— View job

---

Code Review

Reviewing PR #2126: CI cleanup validation changes.

Todo List

• Read CLAUDE.md for repo-specific guidelines
• Review modified .github/workflows/docs-validation.yml
• Review deleted .github/workflows/mintlify-ci.yml
• Review deleted scripts/validate-docs.sh
• Review modified README.md
• Analyze impact and provide feedback

---

Review Summary

This PR simplifies the CI validation setup by removing redundant validation logic and consolidating to use Mintlify's built-in tooling. Overall, this is a good cleanup that reduces maintenance burden. However, there are a few issues to address:

Issues Found

1. ❌ Broken Reference in README.md (Line 40)

Location: README.md:40

The README still references the deleted validation script:

- **Validation fails:** Run `./scripts/validate-docs.sh` and review the output for specific errors

This file no longer exists and will confuse contributors. This line should either be:

• Removed entirely, OR
• Updated to suggest mint broken-links instead

Suggested fix: Fix this →

---

Observations & Recommendations

2. ⚠️ Loss of Validation Checks

The deleted scripts/validate-docs.sh performed several checks that are now removed:

• docs.json validation - Checked JSON syntax and required fields
• Missing MDX file detection - Verified all referenced files exist
• Common syntax issue detection - Basic MDX/JSX linting

Question: Does Mintlify's broken-links command cover these cases? The script also:

• Validated docs.json structure with jq
• Checked for missing files referenced in navigation
• Detected malformed JSX syntax

If these checks are important, you may want to verify that Mintlify's tooling covers them or consider keeping minimal validation.

3. ✅ Workflow Simplification Looks Good

The updated .github/workflows/docs-validation.yml is much cleaner:

• ✅ Removed redundant push trigger (only runs on PRs now)
• ✅ Removed master branch references (main only)
• ✅ Removed unnecessary fetch-depth: 0
• ✅ Updated Node.js from v22 to v24
• ✅ Removed jq installation (no longer needed)
• ✅ Simplified to single npx mintlify broken-links command

4. ✅ mintlify-ci.yml Deletion Justified

The deleted mintlify-ci.yml workflow was mostly placeholder:

• Only echoed messages without real validation
• Minimal checks (just verified docs.json exists)
• Noted that Mintlify Pro/Enterprise has automatic CI

This removal makes sense if relying on Mintlify's native CI integration.

5. ✅ README Cleanup Improves Clarity

The README changes simplify documentation:

• Removed verbose validation section
• Streamlined contributing guidelines
• Removed duplicate Mintlify links
• Kept essential troubleshooting tips

The only issue is the broken reference mentioned in #1.

---

Security & Best Practices

• ✅ No security concerns introduced
• ✅ Dependencies use specific versions (@v5, @v6)
• ✅ No hardcoded secrets or credentials
• ✅ Workflow permissions remain default (appropriate)

---

Summary

Approve with changes: This is a good cleanup that simplifies the validation process. The main blocker is the broken reference in README.md line 40 that needs to be fixed before merging.

Required Changes:

1. Fix the broken script reference in README.md:40

Optional Considerations:

1. Verify that Mintlify's broken-links command covers all the validation cases from the deleted script
2. Consider documenting what validation Mintlify provides to help contributors understand what's being checked

---