Skip to content

docs: unify documentation workflows with improved validation #17522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 24 commits into from

Conversation

EdwardAngert
Copy link
Contributor

Summary

Implementation Details

  • Adds unified JSON-based result aggregation with success percentage calculation
  • Simplifies the preview URL generation while adding direct links to changed docs
  • Organizes steps into logical phases that run concurrently where possible
  • Removes unnecessary metrics tracking (file counts, elapsed time)
  • Fixes branch name handling for GitHub Actions environments
  • Improves cross-reference validation with better heading extraction
  • Updates PR comments with clearer formatting and direct document links

This PR replaces the following PRs:

🤖 Generated with Claude Code

EdwardAngert and others added 17 commits April 9, 2025 18:26
Creates a simplified docs preview action that comments on PRs with Vercel preview links.
The action shows changed files and highlights newly added documentation from manifest.json.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
…o use the same SHA and version (v45.0.7) that the docs-ci.yaml workflow uses.\n\n\ud83e\udd16 Generated with [Claude Code](https://claude.ai/code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\
…d to match patterns from the successful pr-deploy.yaml workflow:\n- Added job-level pull-requests write permission\n- Added explicit env var for PR_NUMBER\n- Added explicit GITHUB_TOKEN environment variable\n- Added reactions-edit-mode for consistency\n\n\ud83e\udd16 Generated with [Claude Code](https://claude.ai/code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\
Create a unified composite action for docs-related workflows:
- Handles file change detection with tj-actions/changed-files
- Provides linting and formatting for markdown files
- Generates preview links for documentation changes
- Creates or updates PR comments with preview links
- Includes special handling for manifest.json changes
- Implements security best practices
- Provides example workflow
Combines features from PRs #17317, #17322, and #17370:
- Adds Vale style checking for documentation
- Creates a reusable workflow for documentation validation
- Optimizes PR checks and post-merge validation
- Adds automatic GitHub issue creation for broken links
- Updates all documentation checks to run in a structured manner

This PR supersedes:
- PR #17317: Docs Preview GitHub Action
- PR #17322: Shared Docs GitHub Action
- PR #17370: Vale Style Checking and Docs Workflow Improvements
- Adds cross-reference validation to detect broken links when files or headings change
- Centralizes file processing for better efficiency
- Creates a reusable docs-setup action to reduce redundancy
- Updates PR comment with cross-reference validation results
- Improves documentation with updated features
- Optimizes code for better maintainability
…ections

- Adds status overview with emoji indicators for each check
- Organizes results into collapsible sections for better readability
- Provides specific guidance on how to fix each type of issue
- Includes detailed contextual information for Vale style issues
- Makes output more scannable and actionable for contributors
- Links to documentation for additional reference
- Move Vale installation to docs-setup action for better reusability
- Remove duplicate Vale installation step from shared action
- Add empty file check to Vale style checking for robustness
- Update workflow to conditionally install Vale based on input parameter
- Make Vale configuration more explicit with improved comments
- Ensure consistent use of pre-processed file lists
- Add unified results aggregation and reporting
- Organize workflow into clear phases for concurrent execution
- Enhance docs-shared action with better dependency structure
- Update post-merge checks to include cross-reference validation
- Remove Slack notification in favor of GitHub issues
- Improve README with updated architecture documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Replace umbrelladocs/action-linkspector with lycheeverse/lychee-action
- Create .lycheeignore file with the same patterns from linkspector
- Update all workflows to use lychee with the new config
- Update action outputs to support lychee's format
- Remove .linkspector.yml as it's no longer needed
- Enhanced documentation to reflect the tool change

Reasons for the change:
- Lychee is faster (written in Rust)
- Better maintained and more widely used
- More flexible configuration options
- Improved error handling and reporting

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Unify all validation checks into a single composite action
- Add validation status aggregation with JSON results
- Simplify preview URL generation with direct document links
- Replace verbose file formatting with targeted doc links
- Improve error handling for all validation steps
- Organize workflow into clear phases for concurrent execution
- Remove file count and time tracking per requirements
- Fix input parameter references for check-format
- Add cross-reference validation with detailed reporting

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Fix branch name extraction with fallbacks for CI environments
- Add conditional handling for PR context in docs-unified workflow
- Improve error handling in cross-reference validation
- Use fixed string matching instead of regex for safer pattern matching
- Remove hardcoded assignee in favor of team assignments
- Improve JSON parsing with proper error handling for lychee results
- Add more reliable newline handling for GitHub issue creation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Add more detailed descriptions of workflow components
- Document status badge generation and thresholds
- Clarify validation options and phases
- Update preview generation details
- Add examples of direct document links
- Improve workflow composite action description

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@EdwardAngert EdwardAngert changed the title Unified documentation workflow with improved validation and reporting docs: unify documentation workflows with improved validation Apr 23, 2025
Copy link

github-actions bot commented Apr 23, 2025

📚 Docs Preview

Your documentation changes are available for preview at:
🔗 Documentation Preview

Changed Documentation Files


🤖 This comment is automatically generated and updated when documentation changes.

EdwardAngert and others added 4 commits April 23, 2025 02:20
- Remove duplicate 'Docs Shared Example' workflows to prevent confusion
- Fix lychee-action configuration in docs-link-check.yaml
- Update node setup cache configuration to include multiple lock files

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Change from ignore-file parameter to --config flag in args
- Use v1 tag instead of pinning to specific version

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Fix indentation in heredoc section to conform to YAML syntax rules

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
EdwardAngert and others added 2 commits April 23, 2025 02:34
- Update references to use ^45 instead of pinned SHAs or specific versions
- This allows automatic minor version updates while keeping major version stable

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Update tj-actions/changed-files to use v45 tag instead of caret versioning
- Fix preview URLs for branches with slashes by replacing with dashes
- Ensure consistent branch name handling across docs-shared and docs-preview actions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@EdwardAngert
Copy link
Contributor Author

#17523

@github-actions github-actions bot locked and limited conversation to collaborators Apr 23, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
docs/site docs site-related issue/task/feature request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant