From 1ea3da40f535fc41041b5078ac4d3fa2630fb4eb Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Fri, 17 Oct 2025 14:57:02 -0400 Subject: [PATCH 1/4] docs(tools): add Vale prose linter section --- .../Helpful-Tools-for-your-Workflow.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md index 86b7077..0b416c4 100644 --- a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md +++ b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md @@ -56,6 +56,26 @@ Ruff can also be set up as part of a pre-commit hook or GitHub Workflow. See the Fast _Markdown_ formatter and linter. We use the [DavidAnson/markdownlint](https://github.com/DavidAnson/markdownlint) package for this site; see instructions and example in the [linting section](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/CONTRIBUTING.md#linting) of our contributing guidelines. It is flexible in configuration and allows for simple checking or even fixing straight-forward formatting issues. +### Vale + +[errata-ai/vale](https://github.com/errata-ai/vale) is a syntax-aware prose linter for documentation, technical writing, and markdown files. Unlike basic spell checkers, Vale enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. + +Vale comes with support for popular style guides like Google, Microsoft, and write-good, and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. + +To lint documentation files, run: + +```bash +vale +``` + +To check an entire directory: + +```bash +vale docs/ +``` + +Vale uses a `.vale.ini` configuration file in your project root to specify style guides, vocabulary, and which files to check. You can also set up Vale as part of a [pre-commit](https://pre-commit.com/) hook or GitHub Workflow to automatically check documentation on commits or pull requests. See the [Vale documentation](https://vale.sh/docs/) for configuration examples and style guide options. + ## FAIR Data Access and Validation Don't add to the reproducibility crisis! Are you using existing data accessed through URLs and need to ensure consistency for re-use? Do you have a folder of images with all their metadata documented through their filenames? [Cautious Robot](#cautious-robot) and [Sum Buddy](#sum-buddy) are here to help. From 3bf499e3ecb033ab4369f878b0bc4f45bfcc693f Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Wed, 28 Jan 2026 13:22:47 -0500 Subject: [PATCH 2/4] Update docs/wiki-guide/Helpful-Tools-for-your-Workflow.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/wiki-guide/Helpful-Tools-for-your-Workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md index 0b416c4..cdfb81b 100644 --- a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md +++ b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md @@ -58,7 +58,7 @@ Fast _Markdown_ formatter and linter. We use the [DavidAnson/markdownlint](https ### Vale -[errata-ai/vale](https://github.com/errata-ai/vale) is a syntax-aware prose linter for documentation, technical writing, and markdown files. Unlike basic spell checkers, Vale enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. +[errata-ai/vale](https://github.com/errata-ai/vale) is a syntax-aware prose linter for documentation, technical writing, and Markdown files. Unlike basic spell checkers, Vale enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. Vale comes with support for popular style guides like Google, Microsoft, and write-good, and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. From 61194471c2985fa5599d46a9294401729db63df7 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Wed, 28 Jan 2026 16:51:13 -0500 Subject: [PATCH 3/4] Update docs/wiki-guide/Helpful-Tools-for-your-Workflow.md Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> --- docs/wiki-guide/Helpful-Tools-for-your-Workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md index cdfb81b..3aa415e 100644 --- a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md +++ b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md @@ -58,7 +58,7 @@ Fast _Markdown_ formatter and linter. We use the [DavidAnson/markdownlint](https ### Vale -[errata-ai/vale](https://github.com/errata-ai/vale) is a syntax-aware prose linter for documentation, technical writing, and Markdown files. Unlike basic spell checkers, Vale enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. +Syntax-aware prose linter for documentation, technical writing, and Markdown files. Unlike basic spell checkers, [errata-ai/vale](https://github.com/errata-ai/vale) enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. Vale comes with support for popular style guides like Google, Microsoft, and write-good, and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. From 6b995620604fc1bfd66d0100e1ee713905df594b Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Wed, 28 Jan 2026 16:59:00 -0500 Subject: [PATCH 4/4] Add hyperlinks to Vale style guides in documentation (#56) * Initial plan * Add hyperlinks to Vale style guides (Google, Microsoft, write-good) Co-authored-by: gwtaylor <993736+gwtaylor@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: gwtaylor <993736+gwtaylor@users.noreply.github.com> --- docs/wiki-guide/Helpful-Tools-for-your-Workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md index 3aa415e..d65864a 100644 --- a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md +++ b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md @@ -60,7 +60,7 @@ Fast _Markdown_ formatter and linter. We use the [DavidAnson/markdownlint](https Syntax-aware prose linter for documentation, technical writing, and Markdown files. Unlike basic spell checkers, [errata-ai/vale](https://github.com/errata-ai/vale) enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. -Vale comes with support for popular style guides like Google, Microsoft, and write-good, and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. +Vale comes with support for popular style guides like [Google](https://github.com/errata-ai/Google), [Microsoft](https://github.com/errata-ai/Microsoft), and [write-good](https://github.com/errata-ai/write-good), and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. To lint documentation files, run: