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

Lines changed: 273 additions & 0 deletions
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy