Skip to content

Commit 6e9bad5

Browse files
EdwardAngertEdwardAngert
committed
refactor: streamline documentation workflow and validation system
- Remove duplicate scheduled checks between weekly-docs and docs-link-check - Update preset configurations to better distribute validation responsibilities - Simplify workflow entry points to rely more on preset defaults - Update Vale integration with inline approach instead of external action - Add two-stage PR comment system with immediate preview links - Update documentation with clearer workflow descriptions
1 parent a5a3d29 commit 6e9bad5

File tree

7 files changed

+232
-119
lines changed

7 files changed

+232
-119
lines changed

‎.github/docs/README.md

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,43 @@ This directory contains GitHub Actions, configurations, and workflows for Coder'
1313
For developers working with documentation, here are the most commonly used commands:
1414

1515
```bash
16-
# Run the comprehensive docs validation
16+
# Run comprehensive documentation validation (markdown lint + link checking)
17+
make lint/docs
18+
19+
# Run only markdown linting
1720
make lint/markdown
1821

22+
# Run optional style checking with Vale (if installed)
23+
make lint/docs-style
24+
1925
# Fix formatting issues
2026
make fmt/markdown # Formats tables and markdown styling
27+
```
28+
29+
## Local vs CI Validation
30+
31+
The validation that runs in CI is available locally through the same Makefile targets:
32+
33+
| GitHub Action | Local Command | Description |
34+
|---------------|--------------|-------------|
35+
| Markdown linting | `make lint/markdown` | Checks markdown formatting |
36+
| Link checking | `make lint/docs` | Verifies links aren't broken |
37+
| Vale style checking | `make lint/docs-style` (optional) | Validates documentation style with Vale |
38+
| Cross-reference validation | *Part of CI only* | Checks references between docs |
39+
40+
### Optional Tool Installation
41+
42+
While basic linting works out-of-the-box with node dependencies, additional tools can be installed for more advanced checks:
43+
44+
```bash
45+
# Install Lychee for link checking (recommended)
46+
cargo install lychee
2147

22-
# Run link checking locally
23-
lychee docs/**/*.md
48+
# Install Vale for style checking (optional)
49+
brew install vale
2450

25-
# Check style with Vale
26-
vale --config=.github/docs/vale/.vale.ini docs/
51+
# Node dependencies for markdown formatting (required)
52+
pnpm install
2753
```
2854

2955
## Workflow Architecture Overview

‎.github/docs/actions/docs-core/action.yaml

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -180,41 +180,41 @@ runs:
180180
if [ -n "${{ inputs.preset }}" ]; then
181181
case "${{ inputs.preset }}" in
182182
"pr")
183-
# PR preset: Full validation with preview for PRs
184-
LINT_MARKDOWN="true"
185-
CHECK_FORMAT="true"
186-
CHECK_LINKS="true"
187-
CHECK_XREFS="true"
188-
LINT_VALE="true"
189-
GEN_PREVIEW="true"
190-
POST_COMMENT="true"
191-
CREATE_ISSUES="false"
192-
FAIL_ON_ERROR="false"
183+
# PR preset: Comprehensive validation with preview for PRs
184+
LINT_MARKDOWN="true" # Ensure markdown format is correct
185+
CHECK_FORMAT="true" # Check table formatting
186+
CHECK_LINKS="true" # Verify all links work
187+
CHECK_XREFS="true" # Check document cross-references
188+
LINT_VALE="true" # Run style checks
189+
GEN_PREVIEW="true" # Generate preview links
190+
POST_COMMENT="true" # Post comment with results
191+
CREATE_ISSUES="false" # No auto-issue creation for PRs
192+
FAIL_ON_ERROR="false" # Don't fail workflow to allow previews with warnings
193193
echo "::notice::Applied PR preset configuration"
194194
;;
195195
"post-merge")
196-
# Post-merge preset: Focus on link checking and issue creation
196+
# Post-merge preset: Lightweight check focused on link integrity
197197
LINT_MARKDOWN="false"
198198
CHECK_FORMAT="false"
199-
CHECK_LINKS="true"
200-
CHECK_XREFS="true"
201-
LINT_VALE="false"
199+
CHECK_LINKS="true" # Only check links after merge to main
200+
CHECK_XREFS="false" # Cross-references should be checked pre-merge
201+
LINT_VALE="false" # Style should be checked pre-merge
202202
GEN_PREVIEW="false"
203203
POST_COMMENT="false"
204-
CREATE_ISSUES="true"
204+
CREATE_ISSUES="false"
205205
FAIL_ON_ERROR="false"
206206
echo "::notice::Applied post-merge preset configuration"
207207
;;
208208
"weekly")
209-
# Weekly check preset: Focus on links with notifications
210-
LINT_MARKDOWN="false"
211-
CHECK_FORMAT="false"
209+
# Weekly check preset: Comprehensive validation with notifications (no style checks)
210+
LINT_MARKDOWN="true"
211+
CHECK_FORMAT="true"
212212
CHECK_LINKS="true"
213213
CHECK_XREFS="true"
214-
LINT_VALE="false"
214+
LINT_VALE="false" # Skip Vale style checking in weekly checks
215215
GEN_PREVIEW="false"
216216
POST_COMMENT="false"
217-
CREATE_ISSUES="true"
217+
CREATE_ISSUES="true" # Create issues for persistent problems
218218
FAIL_ON_ERROR="true"
219219
echo "::notice::Applied weekly check preset configuration"
220220
;;
@@ -688,18 +688,18 @@ runs:
688688
echo "message=Link checking is enabled" >> $GITHUB_OUTPUT
689689
echo "::endgroup::"
690690
691-
# Note: Style checking is now completely handled by errata-ai/vale-action in the unified workflow
691+
# Note: Vale style checking is handled in the unified workflow
692692
# This step exists solely to maintain compatibility with the workflow structure
693693
- name: Report Vale style checking status
694694
id: lint-vale
695695
if: env.lint_vale == 'true' && steps.file-detection.outputs.has_changes == 'true'
696696
shell: bash
697697
run: |
698698
echo "::group::Vale style checking"
699-
echo "Style checking is performed via the Vale GitHub Action"
700-
echo "This step is a placeholder for compatibility with the workflow structure"
699+
echo "Style checking is performed inline in the unified workflow"
700+
echo "This step is a placeholder for result collection"
701701
echo "status=success" >> $GITHUB_OUTPUT
702-
echo "message=See Vale GitHub Action for style validation results" >> $GITHUB_OUTPUT
702+
echo "message=See unified workflow for style validation results" >> $GITHUB_OUTPUT
703703
echo "::endgroup::"
704704
705705
- name: Check for broken cross-references
@@ -921,7 +921,27 @@ runs:
921921
fi
922922
923923
# === GitHub Comment Format ===
924-
GH_COMMENT="# 📚 Documentation Check Results\n\n"
924+
GH_COMMENT="# 📚 Documentation Preview Ready ✅\n\n"
925+
926+
# Show preview link prominently first
927+
if [ "${{ env.gen_preview }}" == "true" ]; then
928+
GH_COMMENT+="## 🖥️ [View Documentation Preview](${{ steps.context-info.outputs.preview_url }})\n\n"
929+
930+
# Add direct links to changed files if available
931+
if [ -n "${{ steps.file-detection.outputs.direct_links }}" ]; then
932+
GH_COMMENT+="### 📄 Changed Files\n\n"
933+
934+
IFS=',' read -ra LINKS <<< "${{ steps.file-detection.outputs.direct_links }}"
935+
for link in "${LINKS[@]}"; do
936+
# Extract the file name for display
937+
filename=$(basename "$link" | sed 's/.md$//')
938+
GH_COMMENT+="- [$filename]($link)\n"
939+
done
940+
GH_COMMENT+="\n"
941+
fi
942+
fi
943+
944+
# Then show validation status
925945
GH_COMMENT+="## 🔎 Status Overview\n\n"
926946
GH_COMMENT+="${{ steps.aggregate-results.outputs.badge }}\n\n"
927947
@@ -940,30 +960,12 @@ runs:
940960
fi
941961
done
942962
943-
# Add preview section
963+
# Add standard documentation links (moved from preview section)
944964
if [ "${{ env.gen_preview }}" == "true" ]; then
945-
GH_COMMENT+="\n## 🖥️ Preview Your Changes\n\n"
946-
GH_COMMENT+="**🔗 [View Documentation Preview](${{ steps.context-info.outputs.preview_url }})**\n\n"
947-
948-
# Add standard documentation links
949-
GH_COMMENT+="### Quick Links\n\n"
965+
GH_COMMENT+="\n### Quick Links\n\n"
950966
GH_COMMENT+="- [Main Docs](${{ steps.context-info.outputs.preview_url }})\n"
951967
GH_COMMENT+="- [Installation Guide](${{ steps.context-info.outputs.install_url }})\n"
952968
GH_COMMENT+="- [Getting Started](${{ steps.context-info.outputs.getting_started_url }})\n\n"
953-
954-
# Add direct links to changed files if available
955-
if [ -n "${{ steps.file-detection.outputs.direct_links }}" ]; then
956-
GH_COMMENT+="<details>\n<summary><strong>📄 Direct Links to Changed Files</strong></summary>\n\n"
957-
958-
IFS=',' read -ra LINKS <<< "${{ steps.file-detection.outputs.direct_links }}"
959-
for link in "${LINKS[@]}"; do
960-
# Extract the file name for display
961-
filename=$(basename "$link" | sed 's/.md$//')
962-
GH_COMMENT+="- [$filename]($link)\n"
963-
done
964-
965-
GH_COMMENT+="</details>\n\n"
966-
fi
967969
fi
968970
969971
# Always add the documentation validation status section
@@ -1006,9 +1008,9 @@ runs:
10061008
10071009
GH_COMMENT+="</details>\n\n"
10081010
1009-
# Add footer
1011+
# Add footer with timestamp
10101012
GH_COMMENT+="---\n"
1011-
GH_COMMENT+="<sub>🤖 This comment is automatically generated and updated when documentation changes.</sub>"
1013+
GH_COMMENT+="<sub>🤖 This comment was last updated on $(date -u "+%Y-%m-%d %H:%M:%S UTC") when validation completed.</sub>"
10121014
10131015
# Output the formatted results
10141016
echo "summary<<EOF" >> $GITHUB_OUTPUT

‎.github/workflows/docs-link-check.yaml

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,7 @@ on:
1010
- '.github/docs/**'
1111
- '.github/workflows/docs-link-check*.yaml'
1212
- '.github/workflows/docs-unified*.yaml'
13-
# Weekly run on Monday at 9 AM
14-
schedule:
15-
- cron: "0 9 * * 1"
13+
# Scheduled runs moved to weekly-docs.yaml
1614
# Allow manual triggering for testing
1715
workflow_dispatch:
1816

@@ -32,15 +30,4 @@ jobs:
3230
preset: 'post-merge'
3331
# Configure notifications
3432
notification-channels: 'github-issue,slack'
35-
issue-labels: 'documentation,bug,needs-triage'
36-
# Post-merge checks for links, cross-references, and style
37-
check-links: true
38-
check-cross-references: true
39-
lint-markdown: false
40-
check-format: false
41-
lint-vale: true
42-
generate-preview: false
43-
post-comment: false
44-
# Don't create issues automatically to avoid flake issues
45-
create-issues: false
46-
fail-on-error: false
33+
issue-labels: 'documentation,bug,needs-triage'

‎.github/workflows/docs-preview.yaml

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,5 @@ jobs:
2323
pull-requests: write
2424
with:
2525
preset: 'pr' # Use the PR preset with all the right configurations
26-
# Override specific parameters for faster preview
27-
check-links: false # Skip link checking for faster preview
28-
check-cross-references: true # Still check cross-references
29-
lint-markdown: true # Quick check for formatting
30-
check-format: true # Quick check for table formatting
31-
lint-vale: true # Add style checking to catch typos like repeated words
32-
generate-preview: true # Always generate preview
33-
post-comment: true # Always post comment
34-
fail-on-error: false # Never fail for preview
35-
notification-channels: '' # No external notifications
26+
# Skip link checking for faster preview
27+
check-links: false

0 commit comments

Comments
 (0)