From 4928f93f1bae429b851ad9f83bc43140ec4ca7e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Tue, 24 Mar 2026 13:44:42 +0100
Subject: [PATCH 1/2] chore(vale): add custom rules and enable em dash
 detection

Add deterministic checks for common style violations: missing admonition
titles, gerund headings, empty image alt text, and sales language.
Extended Languages.yml with GitHub, ChatGPT, MongoDB, PostgreSQL, VS Code,
WordPress, n8n, LangChain. Enabled Microsoft.Dashes for em/en dash detection.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/styles/Apify/AdmonitionTitle.yml |  6 ++++++
 .github/styles/Apify/HeadingGerund.yml   | 14 ++++++++++++++
 .github/styles/Apify/ImageAltText.yml    |  6 ++++++
 .github/styles/Apify/Languages.yml       |  9 ++++++++-
 .github/styles/Apify/SalesLanguage.yml   | 15 +++++++++++++++
 .vale.ini                                |  2 +-
 6 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 .github/styles/Apify/AdmonitionTitle.yml
 create mode 100644 .github/styles/Apify/HeadingGerund.yml
 create mode 100644 .github/styles/Apify/ImageAltText.yml
 create mode 100644 .github/styles/Apify/SalesLanguage.yml

diff --git a/.github/styles/Apify/AdmonitionTitle.yml b/.github/styles/Apify/AdmonitionTitle.yml
new file mode 100644
index 0000000000..3fb4503df1
--- /dev/null
+++ b/.github/styles/Apify/AdmonitionTitle.yml
@@ -0,0 +1,6 @@
+extends: existence
+message: "Admonitions must have titles (e.g., ':::note My title')."
+level: error
+scope: raw
+raw:
+  - ":::(note|tip|info|caution|danger)\\s*\\n"
diff --git a/.github/styles/Apify/HeadingGerund.yml b/.github/styles/Apify/HeadingGerund.yml
new file mode 100644
index 0000000000..e962131979
--- /dev/null
+++ b/.github/styles/Apify/HeadingGerund.yml
@@ -0,0 +1,14 @@
+extends: existence
+message: "Avoid gerunds (-ing) in headings. Use noun phrases or imperatives."
+level: warning
+scope: heading
+tokens:
+  - '^\w+ing\b'
+exceptions:
+  - Billing
+  - Pricing
+  - Debugging
+  - String
+  - Caching
+  - Logging
+  - Troubleshooting
diff --git a/.github/styles/Apify/ImageAltText.yml b/.github/styles/Apify/ImageAltText.yml
new file mode 100644
index 0000000000..634885274f
--- /dev/null
+++ b/.github/styles/Apify/ImageAltText.yml
@@ -0,0 +1,6 @@
+extends: existence
+message: "Images must include meaningful alt text."
+level: error
+scope: raw
+raw:
+  - '!\[\]\('
diff --git a/.github/styles/Apify/Languages.yml b/.github/styles/Apify/Languages.yml
index 518584b2fa..d0d4bf5dc6 100644
--- a/.github/styles/Apify/Languages.yml
+++ b/.github/styles/Apify/Languages.yml
@@ -7,4 +7,11 @@ swap:
   '(?<!-)python(?!-)': Python
   'typescript|Typescript|typescript': TypeScript
   'nodejs|Nodejs|node.js': Node.js
-  # Add more languages or common mistakes as needed
+  'Github': GitHub
+  'chatgpt|Chatgpt|chatGPT': ChatGPT
+  'Mongodb|mongodb': MongoDB
+  'Postgresql|postgresql|postgres': PostgreSQL
+  'vscode|VSCode|VS code': VS Code
+  'Wordpress|wordpress': WordPress
+  'N8n|N8N': n8n
+  'Langchain|langchain': LangChain
diff --git a/.github/styles/Apify/SalesLanguage.yml b/.github/styles/Apify/SalesLanguage.yml
new file mode 100644
index 0000000000..0e7b7f3009
--- /dev/null
+++ b/.github/styles/Apify/SalesLanguage.yml
@@ -0,0 +1,15 @@
+extends: existence
+message: "Avoid sales language. Use factual, specific claims instead."
+level: warning
+scope: sentence
+tokens:
+  - ultimate
+  - cutting-edge
+  - supercharge
+  - best-in-class
+  - game-changing
+  - revolutionary
+  - world-class
+  - next-generation
+  - state-of-the-art
+  - seamless
diff --git a/.vale.ini b/.vale.ini
index b41626451e..b63185ce7a 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -19,7 +19,7 @@ BlockIgnores = (?s) (<!--.*?-->)|(```.*?```)
 # Disabling rules (NO)
 Vale.Spelling = NO
 write-good.ThereIs = NO
-Microsoft.Dashes = NO
+Microsoft.Dashes = YES
 Microsoft.Avoid = NO
 Microsoft.Contractions = NO
 Microsoft.Foreign = NO

From 6b0e5b38c2539e7839e836635cd950fa8af471ce Mon Sep 17 00:00:00 2001
From: Marcel Rebro <marcel.rebro@apify.com>
Date: Wed, 1 Apr 2026 15:47:29 +0200
Subject: [PATCH 2/2] add exceptions to gerund rule

---
 .github/styles/Apify/HeadingGerund.yml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.github/styles/Apify/HeadingGerund.yml b/.github/styles/Apify/HeadingGerund.yml
index e962131979..8e66b7e769 100644
--- a/.github/styles/Apify/HeadingGerund.yml
+++ b/.github/styles/Apify/HeadingGerund.yml
@@ -12,3 +12,17 @@ exceptions:
   - Caching
   - Logging
   - Troubleshooting
+  - Missing
+  - Polling
+  - Timing
+  - Marketing
+  - Existing
+  - Pending
+  - Underlying
+  - Remaining
+  - Corresponding
+  - Incoming
+  - Outgoing
+  - Resulting
+  - Leading
+  - Following