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
coder · EdwardAngert · Apr 9, 2025 · Apr 9, 2025 · Apr 9, 2025 · Apr 9, 2025
commit 0301e900e6689b0b72c87c9b461f88b7b86f133d
diff --git a/.github/docs/.linkspector.yml b/.github/docs/.linkspector.yml
@@ -0,0 +1,22 @@
+# Linkspector configuration file
+ignore:
+  # Ignore patterns for links
+  patterns:
+    - '^\#.*'                      # Anchor links 
+    - '^mailto:.*'                 # Email links
+    - '^https?://localhost.*'      # Local development links
+    - '^https?://127\.0\.0\.1.*'   # Local development links
+    - '^https?://0\.0\.0\.0.*'     # Local development links
+    - '^file:///.*'                # Local file links
+    - '$\{.*\}'                    # Template variables
+
+  # Ignore domains known to be valid but might fail checks
+  domains:
+    - 'github.com'
+    - 'coder.com'
+    - 'example.com'
+    - 'kubernetes.io'
+    - 'k8s.io'
+    - 'docker.com'
+    - 'terraform.io'
+    - 'hashicorp.com'
diff --git a/.github/actions/docs-preview/action.yaml → ...hub/docs/actions/docs-preview/action.yaml b/.github/actions/docs-preview/action.yaml → ...hub/docs/actions/docs-preview/action.yaml
diff --git a/.github/actions/docs-shared/README.md → .github/docs/actions/docs-shared/README.md b/.github/actions/docs-shared/README.md → .github/docs/actions/docs-shared/README.md
@@ -5,7 +5,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
 ## Features
 
 - Detects changes in documentation files using `tj-actions/changed-files`
-- Provides linting and formatting for markdown files
+- Provides linting, style checking, and formatting for markdown files
 - Generates preview links for documentation changes
 - Creates or updates PR comments with preview links
 - Handles special analysis of manifest.json changes
@@ -32,6 +32,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
     check-links: "true"
     lint-markdown: "true"
     format-markdown: "true"
+    lint-vale: "true"
     generate-preview: "true"
     post-comment: "true"
     pr-number: "${{ github.event.pull_request.number }}"
@@ -48,6 +49,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
 | check-links      | Whether to check links in markdown files            | No       | false   |
 | lint-markdown    | Whether to lint markdown files                      | No       | false   |
 | format-markdown  | Whether to check markdown formatting                | No       | false   |
+| lint-vale        | Whether to run Vale style checks on documentation   | No       | true    |
 | generate-preview | Whether to generate preview links                   | No       | false   |
 | post-comment     | Whether to post a PR comment with results           | No       | false   |
 | pr-number        | PR number for commenting                            | No       | ""      |
@@ -68,6 +70,7 @@ A composite GitHub action that provides shared functionality for docs-related wo
 | lint_results          | Results from linting                             |
 | format_results        | Results from format checking                     |
 | link_check_results    | Results from link checking                       |
+| vale_results          | Results from Vale style checks                   |
 
 ## Example
 

diff --git a/.github/actions/docs-shared/action.yaml → .github/docs/actions/docs-shared/action.yaml b/.github/actions/docs-shared/action.yaml → .github/docs/actions/docs-shared/action.yaml
@@ -26,6 +26,10 @@ inputs:
     description: 'Whether to check markdown formatting'
     required: false
     default: 'false'
+  lint-vale:
+    description: 'Whether to run Vale style checks on documentation'
+    required: false
+    default: 'true'
   generate-preview:
     description: 'Whether to generate preview links'
     required: false
@@ -77,6 +81,9 @@ outputs:
   link_check_results:
     description: 'Results from link checking'
     value: ${{ steps.check-links.outputs.result || '' }}
+  vale_results:
+    description: 'Results from Vale style checks'
+    value: ${{ steps.lint-vale.outputs.result || '' }}
 
 runs:
   using: 'composite'
@@ -266,9 +273,33 @@ runs:
       uses: umbrelladocs/action-linkspector@49cf4f8da82db70e691bb8284053add5028fa244 # v1.3.2
       with:
         reporter: github-pr-review
-        config_file: ".github/.linkspector.yml"
+        config_file: ".github/docs/.linkspector.yml"
         fail_on_error: ${{ inputs.fail-on-error }}
         filter_mode: "nofilter"
+
+    - name: Install Vale
+      if: inputs.lint-vale == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
+      uses: errata-ai/vale-action@v2
+      with:
+        config: .github/docs/vale/.vale.ini
+
+    - name: Run Vale style checks
+      if: inputs.lint-vale == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
+      id: lint-vale
+      shell: bash
+      run: |
+        # Run Vale on changed files and capture output
+        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
+
+        echo "result<<EOF" >> $GITHUB_OUTPUT
+        echo "$vale_output" >> $GITHUB_OUTPUT
+        echo "EOF" >> $GITHUB_OUTPUT
+
+        if [ -n "$vale_output" ] && [ "${{ inputs.fail-on-error }}" == "true" ]; then
+          echo "::error::Vale style check found issues:"
+          echo "$vale_output"
+          exit 1
+        fi
 
     - name: Generate Preview URL
       if: inputs.generate-preview == 'true' && steps.docs-analysis.outputs.has_changes == 'true'
@@ -331,6 +362,11 @@ runs:
           ${{ steps.format-docs.outputs.result != '' && steps.format-docs.outputs.result || '' }}
           ${{ steps.format-docs.outputs.result != '' && '```' || '' }}
 
+          ${{ steps.lint-vale.outputs.result != '' && '### Vale Style Issues' || '' }}
+          ${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
+          ${{ steps.lint-vale.outputs.result != '' && steps.lint-vale.outputs.result || '' }}
+          ${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
+
           ---
           <sub>🤖 This comment is automatically generated and updated when documentation changes.</sub>
         edit-mode: replace

diff --git a/.github/docs/vale/.vale.ini b/.github/docs/vale/.vale.ini
@@ -0,0 +1,21 @@
+# Vale configuration file for Coder documentation
+# Based on GitLab Vale configuration using Google and GitLab style guides
+
+StylesPath = styles
+MinAlertLevel = suggestion
+
+# External packages
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Google, write-good
+
+# Ignore code blocks and front matter
+BlockIgnores = (?s)```(.|\n)*?```
+BlockIgnores = (?s){{<[^>]*>}}(.|\n)*?{{</[^>]*>}}
+
+# Vocabulary exceptions
+TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC)
+
+# Project-specific word list
+Vale.Terms = YES
diff --git a/.github/docs/vale/README.md b/.github/docs/vale/README.md
@@ -0,0 +1,35 @@
+# Vale Configuration for Coder Documentation
+
+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.
+
+## Configuration
+
+- `.vale.ini`: Main configuration file that sets up Vale
+- `styles/`: Directory containing style files and rules
+  - `Coder/`: Custom Coder-specific style rules
+    - `Terms.yml`: Coder-specific terminology and preferred terms
+
+## Usage
+
+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.
+
+To test Vale locally:
+
+1. Install Vale: https://vale.sh/docs/vale-cli/installation/
+2. Run Vale on specific files:
+   ```
+   vale --config=.github/vale/.vale.ini path/to/file.md
+   ```
+
+## Rule Sets
+
+The configuration uses these rule sets:
+
+1. **Google**: Style rules from Google's developer documentation style guide
+2. **Write-good**: General style suggestions for clear, concise writing
+3. **Coder**: Custom rules specific to Coder documentation and terminology
+
+## References
+
+- [Vale documentation](https://vale.sh/docs/)
+- [Google developer documentation style guide](https://developers.google.com/style)
diff --git a/.github/docs/vale/styles/Coder/Terms.yml b/.github/docs/vale/styles/Coder/Terms.yml
@@ -0,0 +1,15 @@
+---
+# Coder project-specific terminology and preferred terms
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+swap:
+  'VM': 'virtual machine'
+  'K8s': 'Kubernetes'
+  'kubernetes': 'Kubernetes'
+  'AWS EC2': 'Amazon EC2'
+  'CLI tool': 'CLI'
+  'web UI': 'dashboard'
+  'web ui': 'dashboard'
+  'WebUI': 'dashboard'
diff --git a/.github/workflows/docs-preview.yaml b/.github/workflows/docs-preview.yaml
@@ -54,7 +54,7 @@ jobs:
 
       - name: Generate docs preview
         id: docs-preview
-        uses: ./.github/actions/docs-preview
+        uses: ./.github/docs/actions/docs-preview
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           changed-files: ${{ steps.changed-files.outputs.all_changed_files_json }}

diff --git a/.github/workflows/docs-shared-example.yaml b/.github/workflows/docs-shared-example.yaml
@@ -6,7 +6,7 @@ on:
       - 'docs/**'
       - '**.md'
       - '.github/workflows/docs-shared-example.yaml'
-      - '.github/actions/docs-shared/**'
+      - '.github/docs/actions/docs-shared/**'
 
 permissions:
   contents: read
@@ -40,7 +40,7 @@ jobs:
 
       - name: Process Documentation
         id: docs-shared
-        uses: ./.github/actions/docs-shared
+        uses: ./.github/docs/actions/docs-shared
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           docs-dir: docs

diff --git a/.github/workflows/docs-unified.yaml b/.github/workflows/docs-unified.yaml
@@ -0,0 +1,75 @@
+name: Docs Unified Checks
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'docs/**'
+      - '**.md'
+      - '.github/docs/**'
+      - '.github/workflows/docs-unified.yaml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs-check:
+    name: Documentation Validation
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write # needed for commenting on PRs
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@4d991eb9b905ef189e4c376166672c3f2f230481 # v2.11.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Get PR info
+        id: pr_info
+        run: |
+          set -euo pipefail
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          echo "PR_NUMBER=${PR_NUMBER}" >> $GITHUB_ENV
+          echo "PR_NUMBER=${PR_NUMBER}" >> $GITHUB_OUTPUT
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Process Documentation
+        id: docs-shared
+        uses: ./.github/docs/actions/docs-shared
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          docs-dir: docs
+          include-md-files: "true"
+          check-links: "true"
+          lint-markdown: "true"
+          format-markdown: "true"
+          lint-vale: "true"
+          generate-preview: "true"
+          post-comment: "true"
+          pr-number: "${{ env.PR_NUMBER }}"
+          fail-on-error: "false" # Set to false to show all issues in one run
+
+      - name: Debug Outputs
+        run: |
+          echo "Has changes: ${{ steps.docs-shared.outputs.has_changes }}"
+          echo "Preview URL: ${{ steps.docs-shared.outputs.preview_url }}"
+          echo "Manifest changed: ${{ steps.docs-shared.outputs.manifest_changed }}"
+          echo "New docs found: ${{ steps.docs-shared.outputs.has_new_docs }}"
+
+          # Only display errors if there are any
+          if [ "${{ steps.docs-shared.outputs.lint_results }}" != "" ]; then
+            echo "Linting issues found"
+          fi
+
+          if [ "${{ steps.docs-shared.outputs.format_results }}" != "" ]; then
+            echo "Formatting issues found"
+          fi
+
+          if [ "${{ steps.docs-shared.outputs.vale_results }}" != "" ]; then
+            echo "Vale style issues found"
+          fi
diff --git a/.github/workflows/test-docs-shared.yaml b/.github/workflows/test-docs-shared.yaml
@@ -6,7 +6,7 @@ on:
       - 'docs/**'
       - '**.md'
       - '.github/workflows/docs-shared-example.yaml'
-      - '.github/actions/docs-shared/**'
+      - '.github/docs/actions/docs-shared/**'
 
 permissions:
   contents: read
@@ -40,7 +40,7 @@ jobs:
 
       - name: Process Documentation
         id: docs-shared
-        uses: ./.github/actions/docs-shared
+        uses: ./.github/docs/actions/docs-shared
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           docs-dir: docs