add vale-linter +markdownlint

.github/workflows/vale-check.yml

@@ -0,0 +1,26 @@
+name: Lint Docs
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      # 1. Install Tools (Same as Bitbucket/Local)
+      - name: Install Tools
+        run: |
+          # Install Vale
+          wget https://github.com/errata-ai/vale/releases/download/v3.9.0/vale_3.9.0_Linux_64-bit.tar.gz
+          tar -xvzf vale_3.9.0_Linux_64-bit.tar.gz
+          sudo mv vale /usr/local/bin/
+          # Install Markdownlint
+          npm install -g markdownlint-cli
+
+      # 2. Run your Custom Script
+      - name: Run Quality Check
+        run: |
+          chmod +x docs-linter/lint.sh
+          # Run lint.sh targeting the current directory "."
+          ./docs-linter/lint.sh .

docs-linter/.markdownlint.json

@@ -0,0 +1,12 @@
+{
+  "default": true,
+  "MD013": false, // Line length. Docs often require long lines for links/commands.
+  "MD024": false, // Multiple headings with the same content. Useful for recurring sections like "Parameters".
+  "MD033": false, // Inline HTML. Essential for Docusaurus features (tabs, admonitions, specialized formatting).
+  "MD034": false, // Bare URLs (e.g. https://example.com) without <brackets>. Common in quickstart guides.
+  "MD040": false, // Fenced code blocks must have a language (e.g., ```bash). Good practice, but currently causing errors.
+  "MD041": false, // First line in file must be a top-level heading (H1). Docusaurus uses frontmatter (---) first.
+  "MD047": false, // Files must end with a single newline character. Pedantic and invisible.
+  "MD009": false, // Trailing spaces. Flags every invisible space at the end of a line. Huge noise source.
+  "MD060": false  // Table column style. Flags tables that aren't perfectly ASCII-aligned in the raw text file. Purely visual.
+}

docs-linter/.vale.ini

@@ -0,0 +1,21 @@
+# --- CORE SETTINGS ---
+StylesPath = styles
+MinAlertLevel = suggestion
+Vocab = terms
+Packages = Microsoft, Google, Readability, alex, proselint
+
+# --- GLOBAL IGNORES ---
+IgnoredScopes = code, tt, script, style, pre, figure, strong, b, link.url, a.href
+
+# --- FILE SPECIFIC SETTINGS ---
+[*.{md,mdx}]
+# Put custom-rules AFTER Microsoft so it overrides
+BasedOnStyles = Microsoft, custom-rules
+Vale.Terms = NO
+Microsoft.Terms = NO
+Microsoft.ComplexWords = NO
+
+# --- RULE CONFIGURATION ---
+Microsoft.Contractions = NO
+Microsoft.FirstPerson = NO
+Microsoft.HeadingPunctuation = NO

docs-linter/lint.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+# --- 1. SETUP PATHS ---
+# Determine where this script is located (inside docs-linter)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# The config files are now in the SAME directory as the script
+CONFIG_DIR="$SCRIPT_DIR"
+
+# The target to scan is the first argument, or current directory if empty
+TARGET_DIR="${1:-.}"
+
+# --- 2. VALIDATION ---
+if [ ! -f "$CONFIG_DIR/.vale.ini" ]; then
+    echo "❌ Error: Could not find .vale.ini in $CONFIG_DIR"
+    exit 1
+fi
+
+if [ ! -d "$TARGET_DIR" ]; then
+    echo "❌ Error: Target directory '$TARGET_DIR' does not exist."
+    exit 1
+fi
+
+# --- 3. PREPARE TEMPORARY LOGS ---
+LIST_FILE=$(mktemp)
+VALE_LOG=$(mktemp)
+MD_LOG=$(mktemp)
+VALE_CLEAN=$(mktemp)
+MD_CLEAN=$(mktemp)
+
+# --- 4. GATHER FILES ---
+echo "🎯 Gathering file list from '$TARGET_DIR'..."
+
+# Find markdown files, ignoring node_modules, remotes, and versioned docs
+find "$TARGET_DIR" -type f \( -name "*.md" -o -name "*.mdx" \) \
+    | grep -v "/node_modules/" \
+    | grep -v "/_remotes/" \
+    | grep -v "/versioned_docs/" \
+    > "$LIST_FILE"
+
+FILE_COUNT=$(wc -l < "$LIST_FILE")
+echo "📊 Found $FILE_COUNT files to scan..."
+
+if [ "$FILE_COUNT" -eq 0 ]; then
+    echo "⚠️  No files found to scan."
+    rm "$LIST_FILE" "$VALE_LOG" "$MD_LOG"
+    exit 0
+fi
+
+# --- 5. RUN LINTERS ---
+
+# Check if Vale is installed
+if command -v vale &> /dev/null; then
+    echo "📝 Running Vale..."
+    tr '\n' '\0' < "$LIST_FILE" | xargs -0 -r timeout 5m vale \
+        --config "$CONFIG_DIR/.vale.ini" \
+        --no-wrap \
+        --no-exit \
+        > "$VALE_LOG" 2>&1
+else
+    echo "⚠️  Vale is not installed. Skipping."
+fi
+
+# Check if Markdownlint is installed
+if command -v markdownlint &> /dev/null; then
+    echo "🧹 Running Markdownlint..."
+    tr '\n' '\0' < "$LIST_FILE" | xargs -0 -r timeout 5m markdownlint \
+        --config "$CONFIG_DIR/.markdownlint.json" \
+        > "$MD_LOG" 2>&1 || true
+else
+    echo "⚠️  Markdownlint is not installed. Skipping."
+fi
+
+# --- 6. FORMAT OUTPUT ---
+# Strip absolute paths for readability
+CWD=$(pwd)
+sed "s|$CWD/||g" "$VALE_LOG" | sed 's/\x1b\[[0-9;]*m//g' > "$VALE_CLEAN"
+
+sed "s|$CWD/||g" "$MD_LOG" | sed 's/\x1b\[[0-9;]*m//g' | \
+awk -F: '
+    $1!=last { if(NR>1)print""; print $1; last=$1 }
+    { $1=""; print "  " substr($0,2) }
+' > "$MD_CLEAN"
+
+# --- 7. SUMMARY & REPORT ---
+V_ERR=$(grep -c " error " "$VALE_CLEAN" || true)
+V_WARN=$(grep -c " warning " "$VALE_CLEAN" || true)
+V_SUG=$(grep -c " suggestion " "$VALE_CLEAN" || true)
+MD_ERR=$(grep -c "^  " "$MD_CLEAN" || true)
+TOTAL=$((V_ERR + V_WARN + V_SUG + MD_ERR))
+
+echo ""
+echo "========================================================"
+echo "📊  LINT SUMMARY"
+echo "========================================================"
+echo "  📄 Files Scanned:       $FILE_COUNT"
+echo "  🛑 Vale Errors:         $V_ERR"
+echo "  ⚠️  Vale Warnings:       $V_WARN"
+echo "  💡 Vale Suggestions:    $V_SUG"
+echo "  🧹 Markdownlint Issues: $MD_ERR"
+echo "--------------------------------------------------------"
+echo "  🚨 TOTAL ISSUES:        $TOTAL"
+echo "========================================================"
+echo ""
+
+if [ "$MD_ERR" -gt 0 ]; then
+    echo "########################################################"
+    echo "   MARKDOWNLINT REPORT"
+    echo "########################################################"
+    cat "$MD_CLEAN"
+    echo ""
+fi
+
+if [ $((V_ERR + V_WARN + V_SUG)) -gt 0 ]; then
+    echo "########################################################"
+    echo "   VALE REPORT"
+    echo "########################################################"
+    cat "$VALE_CLEAN"
+    echo ""
+fi
+
+# Cleanup
+rm "$LIST_FILE" "$VALE_LOG" "$MD_LOG" "$VALE_CLEAN" "$MD_CLEAN"
+
+# Optional: Exit with failure if errors found
+# [ "$TOTAL" -gt 0 ] && exit 1 || exit 0

docs-linter/styles/Microsoft/Auto.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "In general, don't hyphenate '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/auto
+ignorecase: true
+level: error
+action:
+  name: convert
+  params:
+    - simple
+tokens:
+  - 'auto-\w+'

docs-linter/styles/Microsoft/ComplexWords.yml

@@ -0,0 +1,14 @@
+extends: substitution
+message: "Consider using '%s' instead of '%s'"
+level: warning
+ignorecase: true
+# This rule swaps complex words for simpler ones (e.g. utilize -> use)
+swap:
+  utilize: use
+  utilization: use
+  facilitate: help
+  leverage: use
+  commence: start
+  terminate: end
+  subsequently: later
+

docs-linter/styles/Microsoft/Contractions.yml

@@ -0,0 +1,50 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions
+level: error
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  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
+  how is: how's
+  is not: isn't
+
+  'it is(?!\.)': it's
+  'it''s(?=\.)': it is
+
+  should not: shouldn't
+
+  "that is(?![.,])": that's
+  'that''s(?=\.)': that is
+
+  'they are(?!\.)': they're
+  'they''re(?=\.)': they are
+
+  was not: wasn't
+
+  'we are(?!\.)': we're
+  'we''re(?=\.)': we are
+
+  'we have(?!\.)': we've
+  'we''ve(?=\.)': we have
+
+  were not: weren't
+
+  'what is(?!\.)': what's
+  'what''s(?=\.)': what is
+
+  'when is(?!\.)': when's
+  'when''s(?=\.)': when is
+
+  'where is(?!\.)': where's
+  'where''s(?=\.)': where is
+
+  will not: won't

docs-linter/styles/Microsoft/Dashes.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Remove the spaces around '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes
+ignorecase: true
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s|\s[—–]|[—–]\s'

docs-linter/styles/Microsoft/DateFormat.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: Use 'July 31, 2016' format, not '%s'.
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\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}'

docs-linter/styles/Microsoft/DateNumbers.yml

@@ -0,0 +1,40 @@
+extends: existence
+message: "Don't use ordinal numbers for dates."
+link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates
+level: error
+nonword: true
+ignorecase: true
+raw:
+  - \b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?)\b\s*
+tokens:
+  - first
+  - second
+  - third
+  - fourth
+  - fifth
+  - sixth
+  - seventh
+  - eighth
+  - ninth
+  - tenth
+  - eleventh
+  - twelfth
+  - thirteenth
+  - fourteenth
+  - fifteenth
+  - sixteenth
+  - seventeenth
+  - eighteenth
+  - nineteenth
+  - twentieth
+  - twenty-first
+  - twenty-second
+  - twenty-third
+  - twenty-fourth
+  - twenty-fifth
+  - twenty-sixth
+  - twenty-seventh
+  - twenty-eighth
+  - twenty-ninth
+  - thirtieth
+  - thirty-first

docs-linter/styles/Microsoft/DateOrder.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Always spell out the name of the month."
+link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\b\d{1,2}/\d{1,2}/(?:\d{4}|\d{2})\b'

docs-linter/styles/Microsoft/Ellipses.yml

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

docs-linter/styles/Microsoft/FirstPerson.yml

@@ -0,0 +1,16 @@
+extends: existence
+message: "Use first person (such as '%s') sparingly."
+link: https://docs.microsoft.com/en-us/style-guide/grammar/person
+ignorecase: true
+level: warning
+nonword: true
+tokens:
+  - (?:^|\s)I(?=\s)
+  - (?:^|\s)I(?=,\s)
+  - \bI'd\b
+  - \bI'll\b
+  - \bI'm\b
+  - \bI've\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b

docs-linter/styles/Microsoft/Gender.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Don't use '%s'."
+link: https://github.com/MicrosoftDocs/microsoft-style-guide/blob/master/styleguide/grammar/nouns-pronouns.md#pronouns-and-gender
+level: error
+ignorecase: true
+tokens:
+  - he/she
+  - s/he

docs-linter/styles/Microsoft/HeadingColons.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Capitalize '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/punctuation/colons
+nonword: true
+level: error
+scope: heading
+tokens:
+  - ':\s[a-z]'