ci: add GitHub Actions workflow for documentation validation

[Nokhrin]

Summary

This PR proposes adding automated documentation link validation using docs-validator, a Python-based static analyzer that detects broken links, orphan files, missing anchors, and circular dependencies in documentation repositories.

Experiment Results

I've tested this tool on the OpenAPI-Specification repository to demonstrate its value. The validation completed in ~45 seconds and analyzed 57 documentation files containing 1,240 links (17 internal, 1,223 external).

Metrics

Metric	Value
Files scanned	57
Total links	1,240
Internal links	17
External links	1,223
Total issues found	84
Broken internal links	9
Broken external links	29
Orphan files	52
Links requiring manual verification	46

Real Issues Discovered

1. Broken Internal Links (9 errors)

• versions/3.0.2.md:1846 → ../examples/v3.0/callback-example.yaml (file not found)
• versions/3.1.0.md:198 → ../examples/v3.1/webhook-example.yaml (file not found)
• _archive_/schemas/v3.0/README.md:38 → ../../tests/v3.0 (file not found)

2. Broken External Links (29 errors)

• versions/1.2.md:92 → http://json-schema.org/latest/json-schema-core.html#anchor8 (404)
• proposals/2019-01-01-Proposal-Template.md:9 → https://github.com/{author2} (404, template placeholder)
• proposals/2024-09-01-Tags-Improvement.md:61 → https://example.com/shopping (404)

3. Orphan Files (52 warnings)
Files without incoming links, potentially undiscoverable:

• versions/3.0.0.md, versions/3.1.0.md, versions/3.2.0.md (historical versions)
• proposals/*.md (15 proposal files)
• .github/pull_request_template.md, .github/ISSUE_TEMPLATE/*.md

4. Manual Verification Required (46 warnings)
Resources blocked by WAF or rate-limited:

• style-guide.md:7 → https://www.npmjs.com/package/markdownlint (403, Cloudflare)
• versions/3.1.2.md:3503 → https://www.w3.org/TR/xml-names11/ (403)
• proposals/2019-10-31-Clarify-Nullable.md:9 → https://github.com/tedepstein (429, rate limit)

Benefits for OpenAPI-Specification

1. Prevent link rot: Automatically detect broken links before they accumulate (already found 38 broken links)
2. Improve discoverability: Identify 52 orphan files that may need better navigation
3. Maintain quality: Ensure all anchors and cross-references remain valid
4. Low maintenance: Once configured, validation runs automatically on PRs
5. Non-blocking: Warnings don't block merges, only errors do

Configuration

The workflow is configured to:

• Run on documentation file changes (.md, .markdown, .asc, .adoc)
• Validate both internal and external links
• Generate a Markdown report as an artifact
• Not fail the build on warnings (only on critical errors)

Known Limitations

The following limitations are documented for transparency:

Limitation	Impact	Mitigation
AsciiDoc support is basic (regex-based)	Medium	Covers ~80% of common use cases; complex macros not parsed
External link validation may produce false positives	Low	Warnings don't block CI; manual verification required for ambiguous cases
Anchor validation covers Markdown headers only	Low	HTML anchors in Markdown files not detected
Performance optimized for CI/CD (changed files only)	Low	Full repository scans available via manual trigger

References

• Tool repository: https://github.com/Nokhrin/docs-validator
• Experimental run: https://github.com/Nokhrin/OpenAPI-Specification/actions/runs/27496526306
• Validation report: docs-validation-report.md
• CI/CD Integration Guide: https://github.com/Nokhrin/docs-validator/blob/main/docs/ci-integration.md

---

I'm happy to adjust the workflow configuration, add a .docs-validator.toml file with project-specific exclusions, or make any other changes based on maintainer feedback.

[karenetheridge]

I don't think we should be running executables out of individual users' repositories. This is not safe.

[Nokhrin]

I understand the security concerns about running executables from individual user repositories. Here are possible solutions:

1. Publish to PyPI: Package the validator and publish it officially, allowing pip install docs-validator with verified releases.
2. Use specific version tags: Pin to a specific commit/tag instead of a branch (e.g., @v1.0.0#commit_hash) for reproducibility.
3. Transfer to OAI organization: Move the repository under OAI's control for official project oversight.
4. Provide security audit documentation: Share code review results, dependency analysis, and security practices.

Could you clarify which approach aligns with OAI's policies?
What specific actions or documentation would be needed to approve this tool for use in the validation workflow?
I'm happy to implement any required changes.
What timeline would work for resolving this?

[ralfhandl]

@Nokhrin What would be the benefits of using your tool in addition to the existing document validation with
https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/validate-markdown.yaml?

[Nokhrin]

@ralfhandl
Linkspector validates external connectivity,
while docs-validator ensures internal documentation integrity by validating anchor existence and file link references in Markdown.
They are complementary.

Commit 7926ee2 (broken markdown anchor)
demonstrates a gap that HTTP-based checkers miss, which the current version of docs-validator already addresses for Markdown files.

However, structural errors like 1397caf (invalid ref syntax)
require semantic analysis beyond link checking.

Would you be open to adding an optional OpenAPI specification validator module? I can implement validation for broken refs, duplicate operationIds, and schema-example mismatches as a configurable rule, keeping the tool modular and auditable.
This would address structural errors without replacing linkspector.