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/.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