fix: resolve YAML syntax issues and add Vale configuration

- Fixed YAML syntax in docs-unified.yaml workflow - Added Vale configuration with basic style rules - Created template file approach for PR comment to avoid syntax issues - Ensured proper Vale directory structure
coder · EdwardAngert · Apr 24, 2025 · Apr 24, 2025 · Apr 24, 2025 · Apr 24, 2025
commit 414280012605508eea6962bdc71ff31a2e78611f
diff --git a/.github/docs/vale/.vale.ini b/.github/docs/vale/.vale.ini
@@ -0,0 +1,16 @@
+# Vale configuration for Coder documentation
+StylesPath = .github/docs/vale/styles
+
+# Minimum alert level
+MinAlertLevel = suggestion
+
+# Files to analyze
+[*.md]
+# Vale styles to use
+BasedOnStyles = Coder, GitLab
+
+# Disable these specific rules
+# Coder.Terms = YES/NO
+
+# Spell checking via Vale
+TokenIgnores = (\w+://\S+) # Ignore URLs
diff --git a/.github/docs/vale/styles/Coder/Headings.yml b/.github/docs/vale/styles/Coder/Headings.yml
@@ -0,0 +1,14 @@
+extends: capitalization
+message: "'%s' should use title case"
+level: warning
+scope: heading
+match: $title
+style: AP # The Associated Press Style Guide
+exceptions:
+  - Coder
+  - CLI
+  - API
+  - UI
+  - SSH
+  - URLs
+  - IP
diff --git a/.github/docs/vale/styles/Coder/RepeatedWords.yml b/.github/docs/vale/styles/Coder/RepeatedWords.yml
@@ -0,0 +1,7 @@
+extends: repetition
+message: "'%s' is repeated"
+level: error
+scope: paragraph
+ignorecase: true
+tokens:
+  - '[a-z]+'
diff --git a/.github/docs/vale/styles/Coder/SentenceLength.yml b/.github/docs/vale/styles/Coder/SentenceLength.yml
@@ -0,0 +1,7 @@
+extends: metric
+message: "Try to keep sentences under 30 words."
+level: suggestion
+scope: sentence
+formula: |
+  size(tokens)
+condition: "> 30"
diff --git a/.github/docs/vale/styles/Coder/Terms.yml b/.github/docs/vale/styles/Coder/Terms.yml
@@ -0,0 +1,13 @@
+extends: substitution
+message: "Use '%s' instead of '%s'"
+level: error
+ignorecase: false
+swap:
+  "(?<!/)coder": Coder
+  "docker container": "Docker container"
+  "kubernetes": Kubernetes
+  "k8s": Kubernetes
+  "YAML file": "YAML file"
+  "yaml file": "YAML file"
+  "json file": "JSON file"
+  "markdown file": "Markdown file"
diff --git a/.github/docs/vale/styles/GitLab/Contractions.yml b/.github/docs/vale/styles/GitLab/Contractions.yml
@@ -0,0 +1,23 @@
+extends: substitution
+message: "Use '%s' instead of '%s'"
+level: warning
+ignorecase: true
+swap:
+  cannot: can't
+  "could not": couldn't
+  "did not": didn't
+  "do not": don't
+  "does not": doesn't
+  "has not": hasn't
+  "have not": haven't
+  "is not": isn't
+  "it is": it's
+  "should not": shouldn't
+  "that is": that's
+  "they are": they're
+  "was not": wasn't
+  "we are": we're
+  "we have": we've
+  "were not": weren't
+  "what is": what's
+  "will not": won't
diff --git a/.github/workflows/docs-unified.yaml b/.github/workflows/docs-unified.yaml
@@ -590,52 +590,64 @@ jobs:
 
           echo "::endgroup::"
 
-      # Prepare comment for PR
+      # Prepare comment for PR using a template file approach
       - name: Prepare PR comment
         id: prepare-comment
         if: inputs.post-comment == 'true' && (inputs.pr-number != '' || github.event.pull_request) && steps.changed-files.outputs.all_changed_files != ''
         shell: bash
         run: |
           echo "::group::Preparing PR comment"
 
-          # Build the comment
+          # Variables for template
           SANITIZED_BRANCH="${{ steps.context-info.outputs.sanitized_branch }}"
           PREVIEW_URL="https://coder.com/docs/@$SANITIZED_BRANCH"
-
-          # Create comment header
+          BADGE="${{ steps.validation-results.outputs.badge }}"
+          FILES="${{ steps.changed-files.outputs.all_changed_files_count }}"
+          SUCCESS="${{ steps.validation-results.outputs.success_percentage }}"
+          PASSING="${{ steps.validation-results.outputs.passing_count }}"
+          TOTAL="${{ steps.validation-results.outputs.validation_count }}"
+          DURATION="${{ steps.validation-duration.outputs.duration }}"
+          WORKFLOW_RUN="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          # Create a temporary file
+          TEMP_FILE=$(mktemp)
+
+          # Create header based on success
           if [ "${{ steps.validation-results.outputs.overall_success }}" == "true" ]; then
-            HEADER="# 📚 Documentation Preview ✅"
-            STATUS_EMOJI="✅"
+            echo "# 📚 Documentation Preview ✅" > $TEMP_FILE
+            EMOJI="✅"
           else
-            HEADER="# 📚 Documentation Preview ⚠️"
-            STATUS_EMOJI="⚠️"
+            echo "# 📚 Documentation Preview ⚠️" > $TEMP_FILE
+            EMOJI="⚠️"
           fi
 
-          # Build the full comment
-          COMMENT="$HEADER
-
-## 🖥️ [View Documentation Preview]($PREVIEW_URL)
-
-> ${STATUS_EMOJI} **Validation Result**: ${{ steps.validation-results.outputs.badge }}
-
-### Quick Links
-- [Main Docs]($PREVIEW_URL)
-- [Installation Guide]($PREVIEW_URL/install)
-- [Quickstart]($PREVIEW_URL/tutorials/quickstart)
-
-### 📊 Validation Stats
-
-- **Changed Files**: ${{ steps.changed-files.outputs.all_changed_files_count }} files checked
-- **Validation Success**: ${{ steps.validation-results.outputs.success_percentage }}% (${{ steps.validation-results.outputs.passing_count }}/${{ steps.validation-results.outputs.validation_count }} checks passed)
-- **Processing Time**: ${{ steps.validation-duration.outputs.duration }}
-
-<sub>⏱️ Validation completed in ${{ steps.validation-duration.outputs.duration }} | [View Workflow Run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})</sub>"
-
-          # Save the comment to output
+          # Add content line by line
+          echo "" >> $TEMP_FILE
+          echo "## 🖥️ [View Documentation Preview]($PREVIEW_URL)" >> $TEMP_FILE
+          echo "" >> $TEMP_FILE
+          echo "> $EMOJI **Validation Result**: $BADGE" >> $TEMP_FILE
+          echo "" >> $TEMP_FILE
+          echo "### Quick Links" >> $TEMP_FILE
+          echo "- [Main Docs]($PREVIEW_URL)" >> $TEMP_FILE
+          echo "- [Installation Guide]($PREVIEW_URL/install)" >> $TEMP_FILE
+          echo "- [Quickstart]($PREVIEW_URL/tutorials/quickstart)" >> $TEMP_FILE
+          echo "" >> $TEMP_FILE
+          echo "### 📊 Validation Stats" >> $TEMP_FILE
+          echo "" >> $TEMP_FILE
+          echo "- **Changed Files**: $FILES files checked" >> $TEMP_FILE
+          echo "- **Validation Success**: $SUCCESS% ($PASSING/$TOTAL checks passed)" >> $TEMP_FILE
+          echo "- **Processing Time**: $DURATION" >> $TEMP_FILE
+          echo "" >> $TEMP_FILE
+          echo "<sub>⏱️ Validation completed in $DURATION | [View Workflow Run]($WORKFLOW_RUN)</sub>" >> $TEMP_FILE
+
+          # Export content to GitHub output
           echo "comment<<EOF" >> $GITHUB_OUTPUT
-          echo "$COMMENT" >> $GITHUB_OUTPUT
+          cat $TEMP_FILE >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
 
+          # Cleanup
+          rm $TEMP_FILE
+
           echo "::endgroup::"
 
       # Update the PR comment with results