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

Lines changed: 22 additions & 0 deletions
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

Lines changed: 4 additions & 1 deletion
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

Lines changed: 37 additions & 1 deletion
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

Lines changed: 21 additions & 0 deletions
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

Lines changed: 35 additions & 0 deletions
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

Lines changed: 15 additions & 0 deletions
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 75 additions & 0 deletions
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

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