From 52eed381bb43a2faf8d8d4135f1c9613465aafa9 Mon Sep 17 00:00:00 2001
From: Brendan Clement <brendan.clement@lancedb.com>
Date: Mon, 19 Oct 2026 12:47:25 -0700
Subject: [PATCH] ci: add an advisory Vale check for documentation prose
 (#4581)

Checks `docs/web` against the shared LanceDB style rules, so the same
mechanical mistakes reach review.

**Change.**

- Add `.vale.ini`, pinning the shared LanceDB Vale package by release
(`vale-lancedb-v0.1.0`), and ignore the synced `.vale/` directory.
- Add the Docs prose style workflow. On pull requests that change
`docs/web` pages or `.vale.ini`, it annotates only added or changed
lines and never fails on a style finding; an install, sync or
configuration error still fails it.
- Link the style guide from `CONTRIBUTING.md` and show how to check a
page locally.


Validation: Tested in [temporary PR
#4595](https://github.com/lancedb/lancedb/pull/4595). Vale flagged all
five deliberate style issues on the changed prose lines, left inline
code and unchanged lines alone, and kept the check green. [Passing
workflow
run](https://github.com/lancedb/lancedb/actions/runs/39299187786/job/118219554825).
---
 .github/workflows/docs-style.yml | 46 ++++++++++++++++++++++++++++++++
 .gitignore                       |  3 +++
 .vale.ini                        |  5 ++++
 CONTRIBUTING.md                  |  9 +++++++
 4 files changed, 63 insertions(+)
 create mode 100644 .github/workflows/docs-style.yml
 create mode 100644 .vale.ini

diff --git a/.github/workflows/docs-style.yml b/.github/workflows/docs-style.yml
new file mode 100644
index 000000000..f0bac9cd0
--- /dev/null
+++ b/.github/workflows/docs-style.yml
@@ -0,0 +1,46 @@
+name: Docs prose style
+
+# Vale checks the mechanical rules in the LanceDB style guide
+# (lancedb/docs, STYLE.md) with the package pinned in .vale.ini. Its findings
+# are advisory annotations on the lines a pull request adds or changes and
+# never fail the job; an install, sync or configuration error still does.
+on:
+  pull_request:
+    paths:
+      - "docs/web/**/*.mdx"
+      - ".vale.ini"
+
+permissions:
+  contents: read
+  pull-requests: read
+
+env:
+  VALE_VERSION: 3.24.0
+  VALE_SHA256: 867534ddb678abca7f214bc4706ead0922bd5252ffe8035fc227013f66c8b214
+
+jobs:
+  prose:
+    name: Lint changed prose
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install Vale
+        run: |
+          archive="vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
+          curl --fail --location --silent --show-error --output "$RUNNER_TEMP/$archive" \
+            "https://github.com/vale-cli/vale/releases/download/v${VALE_VERSION}/$archive"
+          echo "${VALE_SHA256}  $RUNNER_TEMP/$archive" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" vale
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+
+      - name: Annotate changed lines
+        uses: vale-cli/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff # v3.0.0
+        with:
+          version: none
+          files: docs/web
+          reporter: github-pr-annotations
+          filter_mode: added
+          fail_on_error: false
diff --git a/.gitignore b/.gitignore
index 0679f3c8a..61f9edb9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,3 +40,6 @@ dist
 target
 
 **/sccache.log
+
+# Vale styles installed by `vale sync`
+/.vale/
diff --git a/.vale.ini b/.vale.ini
new file mode 100644
index 000000000..13b421863
--- /dev/null
+++ b/.vale.ini
@@ -0,0 +1,5 @@
+# Prose style for the pages in docs/web: the shared LanceDB package, pinned by
+# release. The rules and guide live in lancedb/docs (STYLE.md and vale/).
+# Run `vale sync` once, then `vale docs/web/<page>.mdx`.
+StylesPath = .vale/styles
+Packages = https://github.com/lancedb/docs/releases/download/vale-lancedb-v0.1.0/LanceDB.zip
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0aabd8fec..f7aeac21a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,6 +88,15 @@ npm i -g mint      # https://mintlify.com/docs/installation
 cd docs/web && mint dev
 ```
 
+Wording, names and punctuation follow the
+[LanceDB style guide](https://github.com/lancedb/docs/blob/main/STYLE.md).
+[Vale](https://vale.sh) checks part of it, and pull requests show its
+suggestions on the lines they change. To check a page yourself:
+
+```bash
+vale sync && vale docs/web/indexing/vector-index.mdx
+```
+
 This repository holds a page at every path the site publishes, so the whole
 navigation resolves locally. Enterprise pages exist here as open-source pages --
 what the capability is, and what the embedded form does instead. A separate