Skip to content

Commit ef93173

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 - Fix Vale style checking implementation - Cleanup documentation files
1 parent fc921a5 commit ef93173

File tree

9 files changed

+1694
-0
lines changed

9 files changed

+1694
-0
lines changed

‎.github/docs/README.md

+273
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Coder Documentation Workflow
2+
3+
This directory contains GitHub Actions, configurations, and workflows for Coder's unified documentation validation system.
4+
5+
## Developer Quick Start Guide
6+
7+
```bash
8+
# Check only changed documentation files (default behavior)
9+
make lint/docs
10+
11+
# Check ALL documentation files
12+
make lint/docs --all
13+
14+
# Format markdown tables and fix common issues
15+
make fmt/markdown
16+
17+
# Run Vale style check (optional, requires Vale installation)
18+
make lint/docs-style
19+
```
20+
21+
The validation system will automatically detect and check only files that have changed in your working directory. This ensures fast feedback during development.
22+
23+
## Directory Structure
24+
25+
- `config`: Configuration files for markdown tools (markdownlint, markdown-link-check)
26+
- `vale`: Configuration and style rules for Vale documentation linting
27+
- `testing`: Test scripts and utilities for workflow validation
28+
29+
## Quick Start
30+
31+
For developers working with documentation, here are the most commonly used commands:
32+
33+
```bash
34+
# Run comprehensive documentation validation (markdown lint + link checking)
35+
make lint/docs
36+
37+
# Run only markdown linting
38+
make lint/markdown
39+
40+
# Run optional style checking with Vale (if installed)
41+
make lint/docs-style
42+
43+
# Fix formatting issues
44+
make fmt/markdown # Formats tables and markdown styling
45+
```
46+
47+
## Local vs CI Validation
48+
49+
The validation that runs in CI is available locally through the same Makefile targets:
50+
51+
| GitHub Action | Local Command | Description |
52+
|---------------|--------------|-------------|
53+
| Markdown linting | `make lint/markdown` | Checks markdown formatting |
54+
| Link checking | `make lint/docs` | Verifies links aren't broken |
55+
| Vale style checking | `make lint/docs-style` (optional) | Validates documentation style with Vale |
56+
| Cross-reference validation | *Part of CI only* | Checks references between docs |
57+
58+
### Optional Tool Installation
59+
60+
While basic linting works out-of-the-box with node dependencies, additional tools can be installed for more advanced checks:
61+
62+
```bash
63+
# Install Lychee for link checking (recommended)
64+
cargo install lychee
65+
66+
# Install Vale for style checking (optional)
67+
brew install vale
68+
69+
# Node dependencies for markdown formatting (required)
70+
pnpm install
71+
```
72+
73+
# Coder Documentation Workflow System
74+
75+
## Workflow Architecture
76+
77+
The documentation workflow system uses MegaLinter and standardized GitHub Actions to provide a comprehensive validation pipeline:
78+
79+
```
80+
┌─ Workflow Entry Points ───────────────────────────────────────────────────────┐
81+
│ │
82+
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────┐ │
83+
│ │ PR Preview │ │ Post-Merge │ │ Weekly │ │ CI Check │ │
84+
│ │ Workflow │ │ Validation │ │ Checks │ │ Workflow │ │
85+
│ │ docs-preview.yml│ │ docs-ci.yml │ │weekly-docs.yml │ │docs-ci.yml│ │
86+
│ │ │ │ │ │ │ │ │ │
87+
│ │ • Runs on PR │ │ • Runs after │ │ • Runs weekly │ │ • Runs on │ │
88+
│ │ creation/update│ │ merges to main│ │ on schedule │ │ PR │ │
89+
│ │ • Generates │ │ • Checks links │ │ • Comprehensive │ │ • Basic │ │
90+
│ │ preview links │ │ only │ │ validation │ │ checks │ │
91+
│ │ • Validates docs│ │ • Falls back to │ │ • Planned: issues│ │ • Fast │ │
92+
│ │ • Posts comments│ │ original doc │ │ for problems │ │ feedback│ │
93+
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └─────┬─────┘ │
94+
│ │ │ │ │ │
95+
└───────────┼────────────────────┼────────────────────┼──────────────────┼───────┘
96+
│ │ │ │
97+
└──────────┬─────────┴──────────┬─────────┴──────────┬──────┘
98+
│ │ │
99+
▼ ▼ ▼
100+
┌─ Unified Reusable Workflow ─────────────────────────────────────────────────────┐
101+
│ │
102+
│ docs-unified.yaml │
103+
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
104+
│ │ Configuration System │ │
105+
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
106+
│ │ │ PR Preset │ │Post Preset │ │Weekly Preset│ │ CI Preset │ │ │
107+
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
108+
│ └───────────────────────────────────────────────────────────────────────────┘ │
109+
│ │
110+
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
111+
│ │ Validation Pipeline │ │
112+
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
113+
│ │ │ MegaLinter │ │ Cross-reference│ │ Result Reporting│ │ │
114+
│ │ │ Documentation │ │ Validation │ │ and Comments │ │ │
115+
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
116+
│ └───────────────────────────────────────────────────────────────────────────┘ │
117+
│ │
118+
└─────────────────────────────────────────────────────────────────────────────────┘
119+
│
120+
▼
121+
┌─ Local Development Integration ────────────────────────────────────────────────┐
122+
│ │
123+
│ Makefile targets that mirror workflow functionality: │
124+
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
125+
│ │ make lint/docs│ │make fmt/markdown│ │make lint/markdown│ │make lint/docs-style│ │
126+
│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
127+
│ │
128+
```
129+
130+
## Documentation Workflow Components
131+
132+
### Entry Point Workflows
133+
134+
The system provides four specialized entry points for different validation scenarios:
135+
136+
1. **PR Preview (docs-preview.yaml)**
137+
- Triggers on PR create/update when docs files change
138+
- Performs comprehensive validation on documentation changes
139+
- Generates preview links and posts PR comments with results
140+
- Skips link checking for faster feedback
141+
142+
2. **Post-Merge Validation (docs-link-check.yaml)**
143+
- Runs after merges to main branch
144+
- Lightweight check focused only on link integrity
145+
- Ensures merged content maintains external link validity
146+
147+
3. **Weekly Check (weekly-docs.yaml)**
148+
- Scheduled run every Monday at 9 AM
149+
- Comprehensive validation of documentation health
150+
- Checks links, cross-references, markdown structure, and formatting
151+
- Creates issues for persistent problems
152+
153+
4. **CI Check (docs-ci.yaml)**
154+
- Fast validation for continuous integration
155+
- Focuses on formatting and structural issues
156+
- Designed for rapid feedback
157+
158+
### Unified Workflow & Presets
159+
160+
All entry points use the central `docs-unified.yaml` workflow with different preset configurations:
161+
162+
| Preset | Description | Main Validations | When Used |
163+
|--------|-------------|------------------|-----------|
164+
| `pr` | Complete validation for PRs | markdown, formatting, style, cross-references | PRs that modify docs (preview workflow) |
165+
| `post-merge` | Lightweight check after merge | links | After merging to main (catches broken links) |
166+
| `weekly` | Scheduled health check | markdown, formatting, links, cross-references | Weekly cron job (comprehensive check) |
167+
| `ci` | Fast CI validation | markdown, formatting | PR checks (fast feedback) |
168+
169+
## Key Tools and Integrations
170+
171+
### MegaLinter Documentation Flavor
172+
173+
The workflow leverages MegaLinter's documentation flavor to provide comprehensive validation:
174+
175+
- **markdownlint**: Validates markdown syntax and formatting
176+
- **Vale**: Checks documentation style and terminology
177+
- **markdown-link-check**: Verifies links are valid and accessible
178+
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
183+
184+
### Changed Files Detection
185+
186+
The workflow uses tj-actions/changed-files to efficiently detect changed files:
187+
188+
```yaml
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
197+
```
198+
199+
### Cross-Reference Validation
200+
201+
Custom cross-reference validation checks for broken internal links:
202+
203+
- References to deleted files
204+
- Broken internal markdown links
205+
- Missing image references
206+
207+
## Vale Style Checking
208+
209+
The workflow includes Vale style checking that:
210+
- Only examines changed files to improve performance
211+
- Validates documentation against Coder style guidelines
212+
- Uses the errata-ai/vale-action GitHub Action
213+
- Is configured in `.github/docs/vale/` with custom rules
214+
215+
### Vale Style Rules
216+
217+
The following style rules are configured:
218+
219+
| Rule | Description | Severity |
220+
|------|-------------|----------|
221+
| `Coder.Headings` | Ensures proper heading capitalization | warning |
222+
| `Coder.Terms` | Enforces consistent terminology | warning |
223+
| `Coder.RepeatedWords` | Catches repeated words like "the the" | error |
224+
| `Coder.SentenceLength` | Warns about overly long sentences | suggestion |
225+
| `GitLab.*` | Various rules from GitLab style guide | varies |
226+
227+
To suppress a Vale rule for a specific line:
228+
229+
```markdown
230+
<!-- vale Coder.SentenceLength = NO -->
231+
This is a very long sentence that would normally trigger the sentence length rule but has been explicitly exempted for a good reason such as a technical requirement or quotation.
232+
<!-- vale Coder.SentenceLength = YES -->
233+
```
234+
235+
## Workflow Configuration Options
236+
237+
Each workflow entry point can be customized with these key parameters:
238+
239+
| Parameter | Description | Default |
240+
|-----------|-------------|---------|
241+
| `preset` | Predefined configuration bundle | (required) |
242+
| `lint-markdown` | Run markdown linting | (from preset) |
243+
| `check-format` | Validate table formatting | (from preset) |
244+
| `check-links` | Verify link integrity | (from preset) |
245+
| `check-cross-references` | Check documentation cross-references | (from preset) |
246+
| `lint-vale` | Run Vale style validation | (from preset) |
247+
| `generate-preview` | Create preview links | (from preset) |
248+
| `post-comment` | Post results as PR comment | (from preset) |
249+
| `create-issues` | Create GitHub issues for failures | (from preset) |
250+
| `fail-on-error` | Fail workflow on validation errors | (from preset) |
251+
252+
## Using Documentation Validation in Custom Workflows
253+
254+
To use documentation validation in your own workflows:
255+
256+
```yaml
257+
jobs:
258+
custom-docs-check:
259+
uses: ./.github/workflows/docs-unified.yaml
260+
with:
261+
preset: 'pr' # Choose a preset based on your needs
262+
# Optional overrides
263+
check-links: false # For faster checks
264+
notification-channels: 'slack' # For notifications
265+
```
266+
267+
Available presets:
268+
- `pr`: Full validation with PR comments and preview links
269+
- `post-merge`: Lightweight link checking for merged content
270+
- `weekly`: Comprehensive health check for scheduled runs
271+
- `ci`: Fast validation for continuous integration
272+
273+
The presets provide sensible defaults for each use case, which can be overridden as needed for specific scenarios.

0 commit comments

Comments
 (0)