Skip to content

Commit 0301e90

Browse files
EdwardAngertEdwardAngert
committed
feat(docs): add Vale style checking and reorganize docs workflows
- Add Vale style checking for documentation - Move all docs-related GitHub actions & config to centralized .github/docs directory - Consolidate docs validation in unified workflow - Update all workflows to reference new paths - Add customizable docs terminology rules
1 parent 6a7a2bc commit 0301e90

File tree

11 files changed

+214
-7
lines changed

11 files changed

+214
-7
lines changed

‎.github/docs/.linkspector.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Linkspector configuration file
2+
ignore:
3+
# Ignore patterns for links
4+
patterns:
5+
- '^\#.*' # Anchor links
6+
- '^mailto:.*' # Email links
7+
- '^https?://localhost.*' # Local development links
8+
- '^https?://127\.0\.0\.1.*' # Local development links
9+
- '^https?://0\.0\.0\.0.*' # Local development links
10+
- '^file:///.*' # Local file links
11+
- '$\{.*\}' # Template variables
12+
13+
# Ignore domains known to be valid but might fail checks
14+
domains:
15+
- 'github.com'
16+
- 'coder.com'
17+
- 'example.com'
18+
- 'kubernetes.io'
19+
- 'k8s.io'
20+
- 'docker.com'
21+
- 'terraform.io'
22+
- 'hashicorp.com'

‎.github/actions/docs-preview/action.yaml renamed to ‎.github/docs/actions/docs-preview/action.yaml

File renamed without changes.

‎.github/actions/docs-shared/README.md renamed to ‎.github/docs/actions/docs-shared/README.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
55
## Features
66

77
- Detects changes in documentation files using `tj-actions/changed-files`
8-
- Provides linting and formatting for markdown files
8+
- Provides linting, style checking, and formatting for markdown files
99
- Generates preview links for documentation changes
1010
- Creates or updates PR comments with preview links
1111
- Handles special analysis of manifest.json changes
@@ -32,6 +32,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
3232
check-links: "true"
3333
lint-markdown: "true"
3434
format-markdown: "true"
35+
lint-vale: "true"
3536
generate-preview: "true"
3637
post-comment: "true"
3738
pr-number: "${{ github.event.pull_request.number }}"
@@ -48,6 +49,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
4849
| check-links | Whether to check links in markdown files | No | false |
4950
| lint-markdown | Whether to lint markdown files | No | false |
5051
| format-markdown | Whether to check markdown formatting | No | false |
52+
| lint-vale | Whether to run Vale style checks on documentation | No | true |
5153
| generate-preview | Whether to generate preview links | No | false |
5254
| post-comment | Whether to post a PR comment with results | No | false |
5355
| pr-number | PR number for commenting | No | "" |
@@ -68,6 +70,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
6870
| lint_results | Results from linting |
6971
| format_results | Results from format checking |
7072
| link_check_results | Results from link checking |
73+
| vale_results | Results from Vale style checks |
7174
7275
## Example
7376

‎.github/actions/docs-shared/action.yaml renamed to ‎.github/docs/actions/docs-shared/action.yaml

+37-1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ inputs:
2626
description: 'Whether to check markdown formatting'
2727
required: false
2828
default: 'false'
29+
lint-vale:
30+
description: 'Whether to run Vale style checks on documentation'
31+
required: false
32+
default: 'true'
2933
generate-preview:
3034
description: 'Whether to generate preview links'
3135
required: false
@@ -77,6 +81,9 @@ outputs:
7781
link_check_results:
7882
description: 'Results from link checking'
7983
value: ${{ steps.check-links.outputs.result || '' }}
84+
vale_results:
85+
description: 'Results from Vale style checks'
86+
value: ${{ steps.lint-vale.outputs.result || '' }}
8087

8188
runs:
8289
using: 'composite'
@@ -266,9 +273,33 @@ runs:
266273
uses: umbrelladocs/action-linkspector@49cf4f8da82db70e691bb8284053add5028fa244 # v1.3.2
267274
with:
268275
reporter: github-pr-review
269-
config_file: ".github/.linkspector.yml"
276+
config_file: ".github/docs/.linkspector.yml"
270277
fail_on_error: ${{ inputs.fail-on-error }}
271278
filter_mode: "nofilter"
279+
280+
- name: Install Vale
281+
if: inputs.lint-vale == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
282+
uses: errata-ai/vale-action@v2
283+
with:
284+
config: .github/docs/vale/.vale.ini
285+
286+
- name: Run Vale style checks
287+
if: inputs.lint-vale == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
288+
id: lint-vale
289+
shell: bash
290+
run: |
291+
# Run Vale on changed files and capture output
292+
vale_output=$(echo ${{ steps.changed-files.outputs.all_changed_files }} | tr ',' '\n' | grep '\.md$' | xargs -r vale --config=.github/docs/vale/.vale.ini --output=line 2>&1) || true
293+
294+
echo "result<<EOF" >> $GITHUB_OUTPUT
295+
echo "$vale_output" >> $GITHUB_OUTPUT
296+
echo "EOF" >> $GITHUB_OUTPUT
297+
298+
if [ -n "$vale_output" ] && [ "${{ inputs.fail-on-error }}" == "true" ]; then
299+
echo "::error::Vale style check found issues:"
300+
echo "$vale_output"
301+
exit 1
302+
fi
272303
273304
- name: Generate Preview URL
274305
if: inputs.generate-preview == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
@@ -331,6 +362,11 @@ runs:
331362
${{ steps.format-docs.outputs.result != '' && steps.format-docs.outputs.result || '' }}
332363
${{ steps.format-docs.outputs.result != '' && '```' || '' }}
333364
365+
${{ steps.lint-vale.outputs.result != '' && '### Vale Style Issues' || '' }}
366+
${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
367+
${{ steps.lint-vale.outputs.result != '' && steps.lint-vale.outputs.result || '' }}
368+
${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
369+
334370
---
335371
<sub>🤖 This comment is automatically generated and updated when documentation changes.</sub>
336372
edit-mode: replace

‎.github/docs/vale/.vale.ini

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Vale configuration file for Coder documentation
2+
# Based on GitLab Vale configuration using Google and GitLab style guides
3+
4+
StylesPath = styles
5+
MinAlertLevel = suggestion
6+
7+
# External packages
8+
Packages = Google, write-good
9+
10+
[*.md]
11+
BasedOnStyles = Google, write-good
12+
13+
# Ignore code blocks and front matter
14+
BlockIgnores = (?s)```(.|\n)*?```
15+
BlockIgnores = (?s){{<[^>]*>}}(.|\n)*?{{</[^>]*>}}
16+
17+
# Vocabulary exceptions
18+
TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC)
19+
20+
# Project-specific word list
21+
Vale.Terms = YES

‎.github/docs/vale/README.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Vale Configuration for Coder Documentation
2+
3+
This directory contains the Vale configuration for linting Coder's documentation style. The configuration is based on the Google developer documentation style guide and includes additional Coder-specific terminology rules.
4+
5+
## Configuration
6+
7+
- `.vale.ini`: Main configuration file that sets up Vale
8+
- `styles/`: Directory containing style files and rules
9+
- `Coder/`: Custom Coder-specific style rules
10+
- `Terms.yml`: Coder-specific terminology and preferred terms
11+
12+
## Usage
13+
14+
This Vale configuration is integrated into the docs shared GitHub Action. When a PR includes documentation changes, Vale automatically runs and provides style feedback in the PR comment.
15+
16+
To test Vale locally:
17+
18+
1. Install Vale: https://vale.sh/docs/vale-cli/installation/
19+
2. Run Vale on specific files:
20+
```
21+
vale --config=.github/vale/.vale.ini path/to/file.md
22+
```
23+
24+
## Rule Sets
25+
26+
The configuration uses these rule sets:
27+
28+
1. **Google**: Style rules from Google's developer documentation style guide
29+
2. **Write-good**: General style suggestions for clear, concise writing
30+
3. **Coder**: Custom rules specific to Coder documentation and terminology
31+
32+
## References
33+
34+
- [Vale documentation](https://vale.sh/docs/)
35+
- [Google developer documentation style guide](https://developers.google.com/style)

‎.github/docs/vale/styles/Coder/Terms.yml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
# Coder project-specific terminology and preferred terms
3+
extends: substitution
4+
message: "Use '%s' instead of '%s'."
5+
level: warning
6+
ignorecase: true
7+
swap:
8+
'VM': 'virtual machine'
9+
'K8s': 'Kubernetes'
10+
'kubernetes': 'Kubernetes'
11+
'AWS EC2': 'Amazon EC2'
12+
'CLI tool': 'CLI'
13+
'web UI': 'dashboard'
14+
'web ui': 'dashboard'
15+
'WebUI': 'dashboard'

‎.github/workflows/docs-preview.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ jobs:
5454
5555
- name: Generate docs preview
5656
id: docs-preview
57-
uses: ./.github/actions/docs-preview
57+
uses: ./.github/docs/actions/docs-preview
5858
with:
5959
github-token: ${{ secrets.GITHUB_TOKEN }}
6060
changed-files: ${{ steps.changed-files.outputs.all_changed_files_json }}

‎.github/workflows/docs-shared-example.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ on:
66
- 'docs/**'
77
- '**.md'
88
- '.github/workflows/docs-shared-example.yaml'
9-
- '.github/actions/docs-shared/**'
9+
- '.github/docs/actions/docs-shared/**'
1010

1111
permissions:
1212
contents: read
@@ -40,7 +40,7 @@ jobs:
4040

4141
- name: Process Documentation
4242
id: docs-shared
43-
uses: ./.github/actions/docs-shared
43+
uses: ./.github/docs/actions/docs-shared
4444
with:
4545
github-token: ${{ secrets.GITHUB_TOKEN }}
4646
docs-dir: docs

‎.github/workflows/docs-unified.yaml

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Docs Unified Checks
2+
on:
3+
pull_request:
4+
types: [opened, synchronize, reopened]
5+
paths:
6+
- 'docs/**'
7+
- '**.md'
8+
- '.github/docs/**'
9+
- '.github/workflows/docs-unified.yaml'
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
docs-check:
16+
name: Documentation Validation
17+
runs-on: ubuntu-latest
18+
permissions:
19+
pull-requests: write # needed for commenting on PRs
20+
steps:
21+
- name: Harden Runner
22+
uses: step-security/harden-runner@4d991eb9b905ef189e4c376166672c3f2f230481 # v2.11.0
23+
with:
24+
egress-policy: audit
25+
26+
- name: Checkout
27+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
28+
with:
29+
fetch-depth: 0
30+
31+
- name: Get PR info
32+
id: pr_info
33+
run: |
34+
set -euo pipefail
35+
PR_NUMBER=${{ github.event.pull_request.number }}
36+
echo "PR_NUMBER=${PR_NUMBER}" >> $GITHUB_ENV
37+
echo "PR_NUMBER=${PR_NUMBER}" >> $GITHUB_OUTPUT
38+
env:
39+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
40+
41+
- name: Process Documentation
42+
id: docs-shared
43+
uses: ./.github/docs/actions/docs-shared
44+
with:
45+
github-token: ${{ secrets.GITHUB_TOKEN }}
46+
docs-dir: docs
47+
include-md-files: "true"
48+
check-links: "true"
49+
lint-markdown: "true"
50+
format-markdown: "true"
51+
lint-vale: "true"
52+
generate-preview: "true"
53+
post-comment: "true"
54+
pr-number: "${{ env.PR_NUMBER }}"
55+
fail-on-error: "false" # Set to false to show all issues in one run
56+
57+
- name: Debug Outputs
58+
run: |
59+
echo "Has changes: ${{ steps.docs-shared.outputs.has_changes }}"
60+
echo "Preview URL: ${{ steps.docs-shared.outputs.preview_url }}"
61+
echo "Manifest changed: ${{ steps.docs-shared.outputs.manifest_changed }}"
62+
echo "New docs found: ${{ steps.docs-shared.outputs.has_new_docs }}"
63+
64+
# Only display errors if there are any
65+
if [ "${{ steps.docs-shared.outputs.lint_results }}" != "" ]; then
66+
echo "Linting issues found"
67+
fi
68+
69+
if [ "${{ steps.docs-shared.outputs.format_results }}" != "" ]; then
70+
echo "Formatting issues found"
71+
fi
72+
73+
if [ "${{ steps.docs-shared.outputs.vale_results }}" != "" ]; then
74+
echo "Vale style issues found"
75+
fi

‎.github/workflows/test-docs-shared.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ on:
66
- 'docs/**'
77
- '**.md'
88
- '.github/workflows/docs-shared-example.yaml'
9-
- '.github/actions/docs-shared/**'
9+
- '.github/docs/actions/docs-shared/**'
1010

1111
permissions:
1212
contents: read
@@ -40,7 +40,7 @@ jobs:
4040

4141
- name: Process Documentation
4242
id: docs-shared
43-
uses: ./.github/actions/docs-shared
43+
uses: ./.github/docs/actions/docs-shared
4444
with:
4545
github-token: ${{ secrets.GITHUB_TOKEN }}
4646
docs-dir: docs

0 commit comments

Comments
 (0)