Update Vale configuration

.github/workflows/vale.yml

@@ -0,0 +1,56 @@
+name: Vale
+
+on:
+  pull_request:
+    paths:
+      - "**/*.mdx"
+      - ".vale.ini"
+      - ".vale/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.mdx"
+      - ".vale.ini"
+      - ".vale/**"
+
+jobs:
+  vale:
+    name: Vale linting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Fetch full history for better diff detection
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            **/*.mdx
+          files_ignore: |
+            .vale/**
+            README.md
+
+      - name: Vale (changed files only)
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: ${{ steps.changed-files.outputs.all_changed_files }}
+          vale_flags: "--config=.vale.ini"
+          fail_on_error: false
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Vale (full check on config changes)
+        if: steps.changed-files.outputs.any_changed == 'false'
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: '.'
+          vale_flags: "--config=.vale.ini"
+          fail_on_error: false
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,30 @@
+# Vale configuration for Mintlify documentation
+
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+IgnoredScopes = code, tt, img, url, a
+SkippedScopes = script, style, pre, figure, code
+
+Packages = Google
+
+Vocab = Mintlify
+
+# This is required since Vale doesn't officially support MDX
+[formats]
+mdx = md
+
+# MDX support
+[*.mdx]
+BasedOnStyles = Vale, Google
+Vale.Terms = NO # Enforces really harsh capitalization rules, keep off
+Vale.Avoid = NO # Too aggressive about common technical terms
+
+# Token and block ignores for MDX-specific syntax
+TokenIgnores = (?sm)((?:import|export) .+?$), \
+(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
+(<[A-Z]\w+>.+?<\/[A-Z]\w+>)
+
+BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
+(?sm)^({.+.*})
+
+CommentDelimiters = {/*, */}

.vale/README.md

@@ -0,0 +1,45 @@
+# Vale Configuration for Mintlify Docs
+
+This directory contains the Vale linting configuration for Mintlify documentation.
+
+## Philosophy
+
+Start simple and grow incrementally as needs emerge. The current setup uses:
+
+- Core Mintlify-specific vocabulary
+- Customized rules from the Google developer documentation style guide
+
+## Vale files
+- `.vale.ini` - Main configuration file
+- `styles/config/vocabularies/Mintlify/` - Mintlify-specific terms
+- `styles/Google/` - Google developer documentation style rules customized for Mintlify docs
+
+## When to add vocabulary
+- **Mintlify terms** - New components, features, platform-specific concepts
+- **Frequent false positives** - Any terms that repeatedly trigger spelling errors, but shouldn't
+
+### Discover new vocabulary
+Use the included script to find vocabulary candidates:
+```bash
+# Discover terms from all files
+.vale/scripts/discover-vocabulary.sh
+
+# Discover from specific files
+.vale/scripts/discover-vocabulary.sh "components/*.mdx"
+```
+
+This script:
+1. Runs Vale on specified files
+2. Extracts spelling error suggestions
+3. Saves results to `.vale/vocabulary-candidates.txt`
+
+## When to add new rules
+- **Consistent patterns** - The same style issue appears frequently
+- **High-value, low-noise** - Rules that catch problems with minimal false positives
+
+### Testing new rules
+Before adding a new rule:
+1. Test locally: `vale path/to/file.mdx`
+2. Run on sample files: `vale components/*.mdx`
+3. Check false positive rate
+4. Start with `level: suggestion` then promote to `warning` or `error`

.vale/scripts/discover-vocabulary.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Script to discover potential vocabulary terms from Vale output
+# Usage: ./discover-vocabulary.sh [file-pattern]
+
+set -e
+
+PATTERN=${1:-"**/*.mdx"}
+OUTPUT_FILE=".vale/vocabulary-candidates.txt"
+
+echo "🔍 Discovering vocabulary candidates from Vale spelling errors..."
+echo "Pattern: $PATTERN"
+echo ""
+
+# Run Vale and extract spelling error words
+vale --no-exit $PATTERN 2>&1 | \
+grep "Vale.Spelling" | \
+sed -n "s/.*Did you really mean '\([^']*\)'.*/\1/p" | \
+sort | uniq -c | sort -nr > "$OUTPUT_FILE"
+
+if [ -s "$OUTPUT_FILE" ]; then
+    echo "Found vocabulary candidates in $OUTPUT_FILE:"
+    echo ""
+    head -20 "$OUTPUT_FILE"
+    echo ""
+    echo "Review these terms and add appropriate ones to:"
+    echo "   - .vale/styles/config/vocabularies/Mintlify/accept.txt (if valid)"
+    echo "   - .vale/styles/config/vocabularies/Mintlify/reject.txt (if misspellings)"
+    echo ""
+    echo "To clean up this file: rm $OUTPUT_FILE"
+else
+    echo "✅ No vocabulary issues found!"
+    rm -f "$OUTPUT_FILE"
+fi

.vale/styles/Google/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: "https://developers.google.com/style/word-list"
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.vale/styles/Google/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.vale/styles/Google/DateFormat.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

.vale/styles/Google/Ellipses.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'

.vale/styles/Google/EmDash.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after an em dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+

.vale/styles/Google/Exclamation.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use exclamation points in text."
+link: "https://developers.google.com/style/exclamation-points"
+nonword: true
+level: warning
+action:
+  name: edit
+  params:
+    - trim_right
+    - "!"
+tokens:
+  - '\w+!(?:\s|$)'

.vale/styles/Google/FirstPerson.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid first-person pronouns such as '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+ignorecase: true
+level: warning
+nonword: true
+tokens:
+  - (?:^|\s)I\s
+  - (?:^|\s)I,\s
+  - \bI'm\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b

.vale/styles/Google/HeadingPunctuation.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a period at the end of a heading."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+nonword: true
+level: warning
+scope: heading
+action:
+  name: edit
+  params:
+    - trim_right
+    - "."
+tokens:
+  - '[a-z0-9][.]\s*$'

.vale/styles/Google/Headings.yml

@@ -0,0 +1,38 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+level: warning
+scope: heading
+match: $sentence
+exceptions:
+  - API
+  - APIs
+  - CDN
+  - CORS
+  - CLI
+  - CSS
+  - DNS
+  - GitHub
+  - GitLab
+  - HTML
+  - JavaScript
+  - JSON
+  - JWT
+  - Linux
+  - macOS
+  - Mintlify
+  - MDX
+  - OAuth
+  - OpenAPI
+  - PDF
+  - SAML
+  - SDK
+  - SSL
+  - SSO
+  - TLS
+  - TypeScript
+  - UI
+  - UX
+  - URL
+  - URLs
+  - Windows

.vale/styles/Google/Latin.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+ignorecase: true
+level: error
+nonword: true
+action:
+  name: replace
+swap:
+  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;])': that is

.vale/styles/Google/LyHyphens.yml

@@ -0,0 +1,14 @@
+extends: existence
+message: "'%s' doesn't need a hyphen."
+link: "https://developers.google.com/style/hyphens"
+level: error
+ignorecase: false
+nonword: true
+action:
+  name: edit
+  params:
+    - regex
+    - "-"
+    - " "
+tokens:
+  - '\b[^\s-]+ly-\w+\b'

.vale/styles/Google/OptionalPlurals.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use plurals in parentheses such as in '%s'."
+link: "https://developers.google.com/style/plurals-parentheses"
+level: error
+nonword: true
+action:
+  name: edit
+  params:
+    - trim_right
+    - "(s)"
+tokens:
+  - '\b\w+\(s\)'