Skip to content

Commit 1febdcc

Browse files
EdwardAngertEdwardAngert
committed
refactor: implement docs workflow with MegaLinter and standardized actions
- Replace custom implementation with MegaLinter documentation flavor - Use tj-actions/changed-files for file detection - Create standard configuration files for all tools - Remove complex composite action in favor of pipeline approach - Update documentation to reflect new architecture - Add testing script for validation
1 parent 691c17c commit 1febdcc

File tree

7 files changed

+939
-1376
lines changed

7 files changed

+939
-1376
lines changed

‎.github/docs/README.md

+37-189
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,9 @@ The validation system will automatically detect and check only files that have c
2222

2323
## Directory Structure
2424

25-
- `actions/docs-core`: Primary composite action with the phase-based architecture
25+
- `config`: Configuration files for markdown tools (markdownlint, markdown-link-check)
2626
- `vale`: Configuration and style rules for Vale documentation linting
27-
- `.lycheeignore`: Configuration patterns for lychee link checking
27+
- `testing`: Test scripts and utilities for workflow validation
2828

2929
## Quick Start
3030

@@ -74,7 +74,7 @@ pnpm install
7474

7575
## Workflow Architecture
7676

77-
The documentation workflow system has a clear separation of concerns with multiple layers:
77+
The documentation workflow system uses MegaLinter and standardized GitHub Actions to provide a comprehensive validation pipeline:
7878

7979
```
8080
┌─ Workflow Entry Points ───────────────────────────────────────────────────────┐
@@ -108,33 +108,11 @@ The documentation workflow system has a clear separation of concerns with multip
108108
│ └───────────────────────────────────────────────────────────────────────────┘ │
109109
│ │
110110
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
111-
│ │ Conditional Setup │ │
112-
│ │ • Tool installation (Node.js, PNPM, Vale) │ │
113-
│ │ • Comment posting system │ │
114-
│ │ • Notification handling │ │
115-
│ └───────────────────────────────────────────────────────────────────────────┘ │
116-
│ │
117-
└──────────────────────────────────────┬──────────────────────────────────────────┘
118-
│
119-
▼
120-
┌─ Core Implementation (docs-core/action.yaml) ───────────────────────────────────┐
121-
│ │
122-
│ ┌─── Phase 1: Setup & Detection ───┐ ┌─── Phase 3: Validation ─────────────┐ │
123-
│ │ │ │ │ │
124-
│ │ • Configuration processing │ │ • Markdown linting │ │
125-
│ │ • Environment validation │ │ • Table format checking │ │
126-
│ │ • Changed file detection │ │ • Link validation │ │
127-
│ │ • Advanced fallback mechanisms │ │ • Vale style checking (parallel) │ │
128-
│ │ • File relevance prioritization │ │ • Enhanced cross-reference checks │ │
129-
│ └──────────────────────────────────┘ └──────────────────────────────────────┘ │
130-
│ │
131-
│ ┌─── Phase 4: Results & Reporting ──────────────────────────────────────────┐ │
132-
│ │ │ │
133-
│ │ • Results aggregation and normalization │ │
134-
│ │ • JSON-based validation tracking │ │
135-
│ │ • Two-stage PR comment system │ │
136-
│ │ • Issue reporting │ │
137-
│ │ • Statistics calculation │ │
111+
│ │ Validation Pipeline │ │
112+
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
113+
│ │ │ MegaLinter │ │ Cross-reference│ │ Result Reporting│ │ │
114+
│ │ │ Documentation │ │ Validation │ │ and Comments │ │ │
115+
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
138116
│ └───────────────────────────────────────────────────────────────────────────┘ │
139117
│ │
140118
└─────────────────────────────────────────────────────────────────────────────────┘
@@ -147,13 +125,6 @@ The documentation workflow system has a clear separation of concerns with multip
147125
│ │ make lint/docs│ │make fmt/markdown│ │make lint/markdown│ │make lint/docs-style│ │
148126
│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
149127
│ │
150-
│ Features: │
151-
│ • Automatically detects changed files (git diff) │
152-
│ • Supports both changed-only (default) and all-files (--all) modes │
153-
│ • Uses same validation tools as GitHub Actions │
154-
│ • Provides clear error messages and fix instructions │
155-
│ │
156-
└───────────────────────────────────────────────────────────────────────────────┘
157128
```
158129

159130
## Documentation Workflow Components
@@ -195,91 +166,53 @@ All entry points use the central `docs-unified.yaml` workflow with different pre
195166
| `weekly` | Scheduled health check | markdown, formatting, links, cross-references | Weekly cron job (comprehensive check) |
196167
| `ci` | Fast CI validation | markdown, formatting | PR checks (fast feedback) |
197168

198-
These presets ensure consistent validation based on context without duplicating logic.
169+
## Key Tools and Integrations
199170

200-
#### Preset Configuration Details
171+
### MegaLinter Documentation Flavor
201172

202-
Each preset automatically configures the following settings:
173+
The workflow leverages MegaLinter's documentation flavor to provide comprehensive validation:
203174

204-
**PR Preset:**
205-
```yaml
206-
lint-markdown: true # Format validation
207-
check-format: true # Table format checks
208-
check-links: true # Link validation
209-
check-xrefs: true # Cross-reference validation
210-
lint-vale: true # Style rule checking
211-
gen-preview: true # Generate preview URLs
212-
post-comment: true # Post PR comment with results
213-
create-issues: false # Don't auto-create issues
214-
fail-on-error: false # Allow preview generation even with errors
215-
```
175+
- **markdownlint**: Validates markdown syntax and formatting
176+
- **Vale**: Checks documentation style and terminology
177+
- **markdown-link-check**: Verifies links are valid and accessible
216178

217-
**Post-Merge Preset:**
218-
```yaml
219-
lint-markdown: false # Skip format validation (already checked in PR)
220-
check-format: false # Skip table checks (already checked in PR)
221-
check-links: true # Focus on link validation after content changes
222-
check-xrefs: false # Cross-refs already checked in PR
223-
lint-vale: false # Style already checked in PR
224-
gen-preview: false # No preview needed after merge
225-
post-comment: false # No PR to comment on
226-
create-issues: false # Manual issue review after merge
227-
fail-on-error: false # Record but don't block on errors
228-
```
179+
Configuration files are stored in standardized locations:
180+
- `.github/docs/config/.markdownlint.yml`: Markdown linting rules
181+
- `.github/docs/vale/.vale.ini`: Vale style configuration
182+
- `.github/docs/config/markdown-link-check.json`: Link checking settings
229183

230-
**Weekly Preset:**
231-
```yaml
232-
lint-markdown: true # Comprehensive checks
233-
check-format: true # Comprehensive checks
234-
check-links: true # Comprehensive checks
235-
check-xrefs: true # Comprehensive checks
236-
lint-vale: false # Style not critical for weekly checks
237-
gen-preview: false # No preview needed
238-
post-comment: false # No PR to comment on
239-
create-issues: false # Issue creation feature is planned but not implemented yet
240-
fail-on-error: true # Strict validation
241-
```
184+
### Changed Files Detection
185+
186+
The workflow uses tj-actions/changed-files to efficiently detect changed files:
242187

243-
**CI Preset:**
244188
```yaml
245-
lint-markdown: true # Focus on basic validation
246-
check-format: true # Focus on basic validation
247-
check-links: false # Skip slower checks in CI
248-
check-xrefs: false # Skip slower checks in CI
249-
lint-vale: true # Include style checks
250-
gen-preview: false # No preview in CI
251-
post-comment: false # No comments in CI
252-
create-issues: false # No issues from CI
253-
fail-on-error: true # Fail fast in CI
189+
# Get changed files
190+
- name: Get changed files
191+
id: changed-files
192+
uses: tj-actions/changed-files@v41
193+
with:
194+
files: |
195+
docs/**/*.md
196+
**/*.md
254197
```
255198
256-
## Validation Features
257-
258-
### Two-Stage PR Comment System
199+
### Cross-Reference Validation
259200
260-
The PR workflow implements a two-stage comment system:
201+
Custom cross-reference validation checks for broken internal links:
261202
262-
1. **Initial Comment (Immediate)**
263-
- Posted immediately after checkout and setup
264-
- Provides preview links while validation runs
265-
- Displays a "Validation in progress" status
266-
- Allows reviewers to immediately start reviewing documentation
203+
- References to deleted files
204+
- Broken internal markdown links
205+
- Missing image references
267206
268-
2. **Updated Comment (After Validation)**
269-
- Updates the same comment with validation results
270-
- Shows comprehensive validation status
271-
- Includes direct links to changed files
272-
- Provides validation statistics and duration information
273-
274-
### Vale Style Checking
207+
## Vale Style Checking
275208
276209
The workflow includes Vale style checking that:
277210
- Only examines changed files to improve performance
278211
- Validates documentation against Coder style guidelines
279-
- Runs inline in the workflow (not as a separate action)
212+
- Uses the errata-ai/vale-action GitHub Action
280213
- Is configured in `.github/docs/vale/` with custom rules
281214

282-
#### Vale Style Rules
215+
### Vale Style Rules
283216

284217
The following style rules are configured:
285218

@@ -299,30 +232,6 @@ This is a very long sentence that would normally trigger the sentence length rul
299232
<!-- vale Coder.SentenceLength = YES -->
300233
```
301234

302-
To exempt an entire file, add this at the top:
303-
304-
```markdown
305-
---
306-
vale: false
307-
---
308-
```
309-
310-
### Link and Cross-Reference Verification
311-
312-
Link checking features:
313-
- External link validation with lychee
314-
- Internal cross-reference verification
315-
- Configurable settings and ignore patterns in `.lycheeignore`
316-
- Special handling for manifest.json navigation changes
317-
318-
### Markdown Validation
319-
320-
The workflow validates markdown:
321-
- Structural issues (headings, lists, blockquotes)
322-
- Table formatting and alignment
323-
- Basic stylistic conventions
324-
- Document structure and organization
325-
326235
## Workflow Configuration Options
327236

328237
Each workflow entry point can be customized with these key parameters:
@@ -340,67 +249,6 @@ Each workflow entry point can be customized with these key parameters:
340249
| `create-issues` | Create GitHub issues for failures | (from preset) |
341250
| `fail-on-error` | Fail workflow on validation errors | (from preset) |
342251

343-
## Future Improvements
344-
345-
While the current documentation workflow system is robust and efficient, there are several areas for potential future enhancements:
346-
347-
1. **Incremental Validation**
348-
- Implement only checking files that have changed since the last validation
349-
- Create a dependency graph of documentation files to optimize cross-reference checking
350-
351-
2. **Advanced Link Checking**
352-
- Add specialized handling for API endpoint references
353-
- Implement schema validation for URLs in documentation
354-
- Add validation for image references
355-
356-
3. **Better Local Integration**
357-
- Create a pre-commit hook that runs the same validation locally
358-
- Develop a VSCode extension for real-time documentation validation
359-
360-
4. **Enhanced Reporting**
361-
- Implement trending analysis of documentation issues
362-
- Add visualization of common problem areas
363-
- Create a documentation quality dashboard
364-
365-
5. **Automated Fixes**
366-
- Implement auto-correction for common documentation issues
367-
- Add AI-assisted suggestions for improvement
368-
369-
6. **Integration with External Systems**
370-
- Sync validation results with project management tools
371-
- Implement notification integrations beyond GitHub and Slack
372-
373-
By continuously improving the documentation workflow, we can maintain high-quality documentation while making the validation process more efficient for contributors.
374-
375-
## Troubleshooting
376-
377-
### Common Issues and Solutions
378-
379-
#### File Detection Problems
380-
If changed files aren't being detected correctly:
381-
- The workflow includes fallback mechanisms to ensure validation occurs
382-
- Check workflow logs for fallback notices
383-
- Verify you have changes in the docs/ directory
384-
385-
#### Link Checking Errors
386-
If you see link checking errors:
387-
- Run link checking locally: `lychee docs/**/*.md`
388-
- Add exceptions to `.github/docs/.lycheeignore` if needed
389-
- For internal cross-references, ensure anchors match headers exactly
390-
391-
#### Style Validation Issues
392-
If you encounter Vale style warnings:
393-
- Check specific rules in the output
394-
- Use inline comments to disable specific rules when appropriate:
395-
`<!-- vale StyleName.RuleName = NO -->`
396-
- Consider updating the Vale style rules if the issue occurs frequently
397-
398-
#### Preview URL Issues
399-
The preview URL system converts branch names to URL-friendly format:
400-
- Branch names with slashes are converted to dashes
401-
- Default links are provided even when no files change
402-
- The format is: `https://coder.com/docs/@<branch-name>`
403-
404252
## Using Documentation Validation in Custom Workflows
405253

406254
To use documentation validation in your own workflows:

0 commit comments

Comments
 (0)