From d0b897b74e9200f80e48fa0aeb026b5ad04066c5 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Tue, 26 May 2026 16:02:26 +0200 Subject: [PATCH 01/19] Add Vale config --- .vale.ini | 86 ++++++ .vale/styles/Mendix/Acronyms.yml | 67 +++++ .vale/styles/Mendix/AmericanSpelling.yml | 47 +++ .vale/styles/Mendix/Capitalization.yml | 32 +++ .vale/styles/Mendix/ClickOn.yml | 11 + .vale/styles/Mendix/CompoundWords.yml | 13 + .vale/styles/Mendix/ConditionalAdverbs.yml | 15 + .vale/styles/Mendix/Dashes.yml | 12 + .vale/styles/Mendix/Directions.yml | 15 + .vale/styles/Mendix/HeadingPunctuation.yml | 13 + .vale/styles/Mendix/HeadingTitleCase.yml | 14 + .vale/styles/Mendix/Inclusive.yml | 14 + .vale/styles/Mendix/LinkText.yml | 11 + .vale/styles/Mendix/ListIntroductions.yml | 16 ++ .vale/styles/Mendix/ProductNames.yml | 24 ++ .vale/styles/Mendix/README.md | 86 ++++++ .vale/styles/Mendix/SignIn.yml | 11 + .vale/styles/Microsoft/AMPM.yml | 9 + .vale/styles/Microsoft/Accessibility.yml | 30 ++ .vale/styles/Microsoft/Acronyms.yml | 64 +++++ .vale/styles/Microsoft/Adverbs.yml | 272 ++++++++++++++++++ .vale/styles/Microsoft/Auto.yml | 11 + .vale/styles/Microsoft/Avoid.yml | 14 + .vale/styles/Microsoft/Contractions.yml | 50 ++++ .vale/styles/Microsoft/Dashes.yml | 13 + .vale/styles/Microsoft/DateFormat.yml | 8 + .vale/styles/Microsoft/DateNumbers.yml | 40 +++ .vale/styles/Microsoft/DateOrder.yml | 8 + .vale/styles/Microsoft/Ellipses.yml | 9 + .vale/styles/Microsoft/FirstPerson.yml | 16 ++ .vale/styles/Microsoft/Foreign.yml | 13 + .vale/styles/Microsoft/Gender.yml | 8 + .vale/styles/Microsoft/GenderBias.yml | 42 +++ .vale/styles/Microsoft/GeneralURL.yml | 11 + .vale/styles/Microsoft/HeadingAcronyms.yml | 7 + .vale/styles/Microsoft/HeadingColons.yml | 8 + .vale/styles/Microsoft/HeadingPunctuation.yml | 13 + .vale/styles/Microsoft/Headings.yml | 28 ++ .vale/styles/Microsoft/Hyphens.yml | 14 + .vale/styles/Microsoft/Negative.yml | 13 + .vale/styles/Microsoft/Ordinal.yml | 13 + .vale/styles/Microsoft/OxfordComma.yml | 8 + .vale/styles/Microsoft/Passive.yml | 183 ++++++++++++ .vale/styles/Microsoft/Percentages.yml | 7 + .vale/styles/Microsoft/Plurals.yml | 7 + .vale/styles/Microsoft/Quotes.yml | 7 + .vale/styles/Microsoft/RangeTime.yml | 13 + .vale/styles/Microsoft/Semicolon.yml | 8 + .vale/styles/Microsoft/SentenceLength.yml | 7 + .vale/styles/Microsoft/Spacing.yml | 8 + .vale/styles/Microsoft/Suspended.yml | 7 + .vale/styles/Microsoft/Terms.yml | 42 +++ .vale/styles/Microsoft/URLFormat.yml | 9 + .vale/styles/Microsoft/Units.yml | 16 ++ .vale/styles/Microsoft/Vocab.yml | 25 ++ .vale/styles/Microsoft/We.yml | 11 + .vale/styles/Microsoft/Wordiness.yml | 127 ++++++++ .vale/styles/Microsoft/meta.json | 4 + 58 files changed, 1690 insertions(+) create mode 100644 .vale.ini create mode 100644 .vale/styles/Mendix/Acronyms.yml create mode 100644 .vale/styles/Mendix/AmericanSpelling.yml create mode 100644 .vale/styles/Mendix/Capitalization.yml create mode 100644 .vale/styles/Mendix/ClickOn.yml create mode 100644 .vale/styles/Mendix/CompoundWords.yml create mode 100644 .vale/styles/Mendix/ConditionalAdverbs.yml create mode 100644 .vale/styles/Mendix/Dashes.yml create mode 100644 .vale/styles/Mendix/Directions.yml create mode 100644 .vale/styles/Mendix/HeadingPunctuation.yml create mode 100644 .vale/styles/Mendix/HeadingTitleCase.yml create mode 100644 .vale/styles/Mendix/Inclusive.yml create mode 100644 .vale/styles/Mendix/LinkText.yml create mode 100644 .vale/styles/Mendix/ListIntroductions.yml create mode 100644 .vale/styles/Mendix/ProductNames.yml create mode 100644 .vale/styles/Mendix/README.md create mode 100644 .vale/styles/Mendix/SignIn.yml create mode 100644 .vale/styles/Microsoft/AMPM.yml create mode 100644 .vale/styles/Microsoft/Accessibility.yml create mode 100644 .vale/styles/Microsoft/Acronyms.yml create mode 100644 .vale/styles/Microsoft/Adverbs.yml create mode 100644 .vale/styles/Microsoft/Auto.yml create mode 100644 .vale/styles/Microsoft/Avoid.yml create mode 100644 .vale/styles/Microsoft/Contractions.yml create mode 100644 .vale/styles/Microsoft/Dashes.yml create mode 100644 .vale/styles/Microsoft/DateFormat.yml create mode 100644 .vale/styles/Microsoft/DateNumbers.yml create mode 100644 .vale/styles/Microsoft/DateOrder.yml create mode 100644 .vale/styles/Microsoft/Ellipses.yml create mode 100644 .vale/styles/Microsoft/FirstPerson.yml create mode 100644 .vale/styles/Microsoft/Foreign.yml create mode 100644 .vale/styles/Microsoft/Gender.yml create mode 100644 .vale/styles/Microsoft/GenderBias.yml create mode 100644 .vale/styles/Microsoft/GeneralURL.yml create mode 100644 .vale/styles/Microsoft/HeadingAcronyms.yml create mode 100644 .vale/styles/Microsoft/HeadingColons.yml create mode 100644 .vale/styles/Microsoft/HeadingPunctuation.yml create mode 100644 .vale/styles/Microsoft/Headings.yml create mode 100644 .vale/styles/Microsoft/Hyphens.yml create mode 100644 .vale/styles/Microsoft/Negative.yml create mode 100644 .vale/styles/Microsoft/Ordinal.yml create mode 100644 .vale/styles/Microsoft/OxfordComma.yml create mode 100644 .vale/styles/Microsoft/Passive.yml create mode 100644 .vale/styles/Microsoft/Percentages.yml create mode 100644 .vale/styles/Microsoft/Plurals.yml create mode 100644 .vale/styles/Microsoft/Quotes.yml create mode 100644 .vale/styles/Microsoft/RangeTime.yml create mode 100644 .vale/styles/Microsoft/Semicolon.yml create mode 100644 .vale/styles/Microsoft/SentenceLength.yml create mode 100644 .vale/styles/Microsoft/Spacing.yml create mode 100644 .vale/styles/Microsoft/Suspended.yml create mode 100644 .vale/styles/Microsoft/Terms.yml create mode 100644 .vale/styles/Microsoft/URLFormat.yml create mode 100644 .vale/styles/Microsoft/Units.yml create mode 100644 .vale/styles/Microsoft/Vocab.yml create mode 100644 .vale/styles/Microsoft/We.yml create mode 100644 .vale/styles/Microsoft/Wordiness.yml create mode 100644 .vale/styles/Microsoft/meta.json diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000..20556a65626 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,86 @@ +# Vale configuration for Mendix documentation +# See: https://vale.sh/docs/topics/config/ + +StylesPath = .vale/styles +MinAlertLevel = suggestion + +# Packages to sync from vale.sh +# Microsoft = Microsoft Writing Style Guide +Packages = Microsoft + +# Ignore patterns +[*.{md,mdx}] +# Ignore code blocks +BlockIgnores = (?s) *```(?:[\w\{\}]+)?$(.+?)^ *``` +# Ignore front matter (YAML blocks at start of file), anchor IDs in headings, and Hugo shortcodes +# Content matched by TokenIgnores is treated as 'raw' scope by Vale +# Rules must use scope: '!raw' to exclude front matter +TokenIgnores = (\A---\s*\n(.|\n)+?\n---\s*\n), (\{#[^\}]+\}), (\{\{[^\}]+\}\}) + +# Markdown files use both Microsoft and custom Mendix styles +BasedOnStyles = Microsoft, Mendix + +# ============================================================================ +# Microsoft Style Guide Rule Overrides +# ============================================================================ +# The following rules are disabled or adjusted to align with Mendix style guide +# requirements documented in content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/ + +# Acronyms +# Microsoft requires title case for acronym definitions; Mendix allows sentence case too +# Replacement: Mendix.Acronyms accepts sentence-case definitions +Microsoft.Acronyms = NO + +# Contractions +# Microsoft requires contractions; Mendix prohibits them +# Mendix style guide: "Do not use contractions. Write 'it is' and not 'it's.'" +Microsoft.Contractions = NO + +# Dashes +# Microsoft removes all spaces around em/en dashes; Mendix has context-specific rules +# Mendix style guide: Em dashes (—) have no spaces; en dashes (–) have spaces except in number ranges +# Replacement: Mendix.Dashes enforces en dash spacing in number ranges and between words +# Mendix.ListIntroductions enforces en dashes (not em dashes) for list item introductions +Microsoft.Dashes = NO + +# General URL +# Microsoft prefers "address" over "URL"; Mendix does not +Microsoft.GeneralURL = NO + +# Heading Acronyms +# Microsoft prohibits acronyms in headings; Mendix does not +Microsoft.HeadingAcronyms = NO + +# Heading Capitalization +# Microsoft suggests sentence-style; Mendix requires title case +# Mendix style guide: "Use title case for titles and headings" +# Replacement: Mendix.HeadingTitleCase enforces title case capitalization +Microsoft.Headings = NO + +# Heading Punctuation +# Microsoft prohibits all end punctuation; Mendix allows question marks +# Replacement: Mendix.HeadingPunctuation prohibits periods, exclamation marks, and colons but allows question marks +Microsoft.HeadingPunctuation = NO + +# Spacing +# Technical content like **StationConnector.Administrator** triggers false positives +Microsoft.Spacing = NO + +# Terms +# Too far off from Mendix terminology guidance +Microsoft.Terms = NO + +# ============================================================================ +# Path-Specific Overrides +# ============================================================================ + +# First-Person Plural +# Release notes allow first-person plural "we" +[content/en/docs/releasenotes/*.md] +Microsoft.We = NO + +# Product Names +# Disable deprecated product name checks in historical documentation +# These versions used older terminology that may have been accurate at the time +[content/en/docs/{refguide8,refguide9,refguide10,howto8,howto9,howto10,releasenotes}/**/*.md] +Mendix.ProductNames = NO \ No newline at end of file diff --git a/.vale/styles/Mendix/Acronyms.yml b/.vale/styles/Mendix/Acronyms.yml new file mode 100644 index 00000000000..444a36841e4 --- /dev/null +++ b/.vale/styles/Mendix/Acronyms.yml @@ -0,0 +1,67 @@ +extends: conditional +message: "Define '%s' on first use." +link: https://docs.microsoft.com/en-us/style-guide/acronyms +level: suggestion +ignorecase: false +scope: '!raw' +# Ensures that the existence of 'first' implies the existence of 'second'. +# Modified from Microsoft.Acronyms to accept sentence-case definitions +# e.g., "personal access token (PAT)" not just "Personal Access Token (PAT)" +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Za-z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.vale/styles/Mendix/AmericanSpelling.yml b/.vale/styles/Mendix/AmericanSpelling.yml new file mode 100644 index 00000000000..8ba8f162db8 --- /dev/null +++ b/.vale/styles/Mendix/AmericanSpelling.yml @@ -0,0 +1,47 @@ +extends: substitution +message: "Use American English spelling '%s' instead of '%s'." +link: https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words +ignorecase: true +level: error +nonword: false +# Exclude code, comments, and raw content (front matter, shortcodes, anchor IDs) +scope: text +action: + name: replace +swap: + # -ise/-ize patterns + '\b(organ|real|recogn|standard|normal|legal|special|general|minim|maxim|optim|neutral|central|character|categor|formal|final|visual|modern|popular|personal|national|local|global|digital|custom|util|mobil|stabil|prior|anal|summar|critic|emphas|synchron)ise([ds])?\b': '$1ize$2' + + # -our/-or patterns + '\b(col|behavi|fav|neighb|lab|hon|hum|sav|harb)our([s]?)\b': '$1or$2' + + # -re/-er patterns + '\bcentre([ds])?\b': 'center$1' + '\btheatre([ds])?\b': 'theater$1' + + # -ence/-ense patterns + '\bdefence([s]?)\b': 'defense$1' + '\blicence([s]?)\b': 'license$1' + '\boffence([s]?)\b': 'offense$1' + '\bpretence([s]?)\b': 'pretense$1' + + # -logue/-log patterns + '\bcatalogue([ds])?\b': 'catalog$1' + '\bdialogue([ds])?\b': 'dialog$1' + + # Double-L patterns + '\bcancell(ed|ing)\b': 'cancel$1' + '\btravell(ed|ing|er)\b': 'travel$1' + '\bmodell(ed|ing)\b': 'model$1' + + # Common individual words + '\bgrey\b': 'gray' + '\bwhilst\b': 'while' + '\bamongst\b': 'among' + '\btowards\b': 'toward' + '\bafterwards\b': 'afterward' + '\bbackwards\b': 'backward' + '\bforwards\b': 'forward' + '\bupwards\b': 'upward' + '\bdownwards\b': 'downward' + '\bprogramme([ds])?\b': 'program$1' diff --git a/.vale/styles/Mendix/Capitalization.yml b/.vale/styles/Mendix/Capitalization.yml new file mode 100644 index 00000000000..66504396bf9 --- /dev/null +++ b/.vale/styles/Mendix/Capitalization.yml @@ -0,0 +1,32 @@ +# Mendix custom rule: Capitalization errors +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Capitalization of Mendix Terminology) +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md +extends: substitution +message: "Use '%s' (capitalized)" +level: error +ignorecase: true +scope: '!raw' +swap: + agents kit: Agents Kit + boolean: Boolean + git: Git + java: Java + marketplace: Marketplace + mendix: Mendix + 'n/a': 'N/A' + postgres: Postgres + postgresql: PostgreSQL + scrum: Scrum + sprint: Sprint + sql: SQL + 'atlas ui': 'Atlas UI' + 'build server': 'Build Server' + 'business engineer': 'Business Engineer' + 'control center': 'Control Center' + 'model server': 'Model Server' + 'product owner': 'Product Owner' + 'scrum master': 'Scrum Master' + 'studio pro': 'Studio Pro' + 'team server': 'Team Server' + 'technical contact': 'Technical Contact' + 'workflow engine': 'Workflow Engine' diff --git a/.vale/styles/Mendix/ClickOn.yml b/.vale/styles/Mendix/ClickOn.yml new file mode 100644 index 00000000000..a32f3808d79 --- /dev/null +++ b/.vale/styles/Mendix/ClickOn.yml @@ -0,0 +1,11 @@ +# Mendix custom rule: Use 'click' not 'click on' +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (click) +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + 'click on': 'click' + 'clicking on': 'clicking' + 'clicked on': 'clicked' + 'clicks on': 'clicks' diff --git a/.vale/styles/Mendix/CompoundWords.yml b/.vale/styles/Mendix/CompoundWords.yml new file mode 100644 index 00000000000..78abd4bb608 --- /dev/null +++ b/.vale/styles/Mendix/CompoundWords.yml @@ -0,0 +1,13 @@ +# Mendix custom rule: Compound word formatting +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md +# See specific terms: checkbox, dataset, endpoint, home page +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + 'data-set': 'dataset' + 'data set': 'dataset' + 'end point': 'endpoint' + 'check box': 'checkbox' + 'home-page': 'home page' diff --git a/.vale/styles/Mendix/ConditionalAdverbs.yml b/.vale/styles/Mendix/ConditionalAdverbs.yml new file mode 100644 index 00000000000..18f2b3dea57 --- /dev/null +++ b/.vale/styles/Mendix/ConditionalAdverbs.yml @@ -0,0 +1,15 @@ +# Mendix custom rule: Avoid conditional adverbs that add uncertainty +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Conditional Adverbs) +# "These words add uncertainty and cloud the meaning of sentences." +extends: existence +message: "Avoid '%s'. These words add uncertainty to technical writing." +level: warning +ignorecase: true +tokens: + - '\bwould\b' + - '\bcould\b' + - '\bshould\b' + - '\bpossibly\b' + - '\bmight\b' + - '\bactually\b' + - '\bpotentially\b' diff --git a/.vale/styles/Mendix/Dashes.yml b/.vale/styles/Mendix/Dashes.yml new file mode 100644 index 00000000000..a8239f9793d --- /dev/null +++ b/.vale/styles/Mendix/Dashes.yml @@ -0,0 +1,12 @@ +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Dashes) +extends: substitution +message: "Remove spaces around em dashes (—)." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes +ignorecase: false +nonword: true +level: error +swap: + # Em dashes (—) should not have spaces + ' — ': '—' + ' —': '—' + '— ': '—' diff --git a/.vale/styles/Mendix/Directions.yml b/.vale/styles/Mendix/Directions.yml new file mode 100644 index 00000000000..66409cfedbe --- /dev/null +++ b/.vale/styles/Mendix/Directions.yml @@ -0,0 +1,15 @@ +# Mendix custom rule: Use upper/lower instead of top/bottom +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (lower-left/lower-right) +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + 'top left': 'upper left' + 'top-left': 'upper-left' + 'top right': 'upper right' + 'top-right': 'upper-right' + 'bottom left': 'lower left' + 'bottom-left': 'lower-left' + 'bottom right': 'lower right' + 'bottom-right': 'lower-right' diff --git a/.vale/styles/Mendix/HeadingPunctuation.yml b/.vale/styles/Mendix/HeadingPunctuation.yml new file mode 100644 index 00000000000..a1bb9e55e87 --- /dev/null +++ b/.vale/styles/Mendix/HeadingPunctuation.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Remove end punctuation from headings (except question marks)." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +nonword: true +level: warning +scope: heading +action: + name: edit + params: + - trim_right + - ".!:" +tokens: + - "[a-z][.!:;]$" diff --git a/.vale/styles/Mendix/HeadingTitleCase.yml b/.vale/styles/Mendix/HeadingTitleCase.yml new file mode 100644 index 00000000000..470c2d622f4 --- /dev/null +++ b/.vale/styles/Mendix/HeadingTitleCase.yml @@ -0,0 +1,14 @@ +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Headings and Titles) +extends: capitalization +message: "Use title case capitalization for '%s'." +level: warning +scope: heading +match: $title +style: Chicago +indicators: + - ':' +exceptions: + # Words with non-standard capitalization that shouldn't be modified + - macOS + - iOS + - IdP \ No newline at end of file diff --git a/.vale/styles/Mendix/Inclusive.yml b/.vale/styles/Mendix/Inclusive.yml new file mode 100644 index 00000000000..4be20a375f3 --- /dev/null +++ b/.vale/styles/Mendix/Inclusive.yml @@ -0,0 +1,14 @@ +# Mendix custom rule: Inclusive language +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + blacklist: blocklist + whitelist: allowlist + slave: follower + 'he/she': they + 'his/her': their + 'his or her': their + 'he or she': they diff --git a/.vale/styles/Mendix/LinkText.yml b/.vale/styles/Mendix/LinkText.yml new file mode 100644 index 00000000000..72f5876629c --- /dev/null +++ b/.vale/styles/Mendix/LinkText.yml @@ -0,0 +1,11 @@ +# Mendix custom rule: Avoid generic link text +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Links) +# Reference: CLAUDE.md (Line 85: "Use descriptive link text such as the page title, not 'click here'") +extends: existence +message: "Use descriptive link text instead of '%s'." +link: https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html +level: error +ignorecase: true +scope: raw +raw: + - '\[(?:click here|here|this link|this page|link|read more)\]\(' diff --git a/.vale/styles/Mendix/ListIntroductions.yml b/.vale/styles/Mendix/ListIntroductions.yml new file mode 100644 index 00000000000..f79f07eec0f --- /dev/null +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -0,0 +1,16 @@ +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Lists) +extends: substitution +message: "Set off list item introductions with an en dash (–), not an em dash (—)." +ignorecase: false +nonword: true +level: error +scope: list +swap: + # Match up to 40 chars + word/slash/digit + space + em dash + space + '^.{0,40}([a-zA-Z0-9/]) — ': '$1 – ' + # Match up to 40 chars + word/slash/digit + space + em dash no trailing space + '^.{0,40}([a-zA-Z0-9/]) —': '$1 – ' + # Match up to 40 chars + word/slash/digit + em dash + space no leading space + '^.{0,40}([a-zA-Z0-9/])— ': '$1 – ' + # Match up to 40 chars + word/slash/digit + em dash no spaces + '^.{0,40}([a-zA-Z0-9/])—': '$1 – ' diff --git a/.vale/styles/Mendix/ProductNames.yml b/.vale/styles/Mendix/ProductNames.yml new file mode 100644 index 00000000000..77c327f3813 --- /dev/null +++ b/.vale/styles/Mendix/ProductNames.yml @@ -0,0 +1,24 @@ +# Mendix custom rule: Deprecated product names +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: false +swap: + # Main product deprecated names + 'Mendix for Private Cloud': 'Mendix on Kubernetes' + 'Business Engine': 'Mendix Runtime' + 'Mendix Business Server': 'Mendix Runtime' + 'Mendix Server': 'Mendix Runtime' + 'Sprintr': 'Apps' + 'Developer Portal': 'Apps' + 'Platform Portal': 'Apps' + 'Mendix App Platform': 'Apps' + 'Data Hub': 'Catalog' + 'Mendix Forum': 'Mendix Community' + 'Developer Profile': 'Mendix Profile' + 'Mendix Mobile app': 'Mendix Developer App' + 'Mendix Administrator': 'Mendix Admin' + 'Native Oven': 'Native Builder' + 'MxAssist': 'Maia' + 'Mendix Assist': 'Maia' \ No newline at end of file diff --git a/.vale/styles/Mendix/README.md b/.vale/styles/Mendix/README.md new file mode 100644 index 00000000000..c4abd13805a --- /dev/null +++ b/.vale/styles/Mendix/README.md @@ -0,0 +1,86 @@ +# Mendix Custom Vale Rules + +This directory contains custom Vale rules specific to Mendix documentation. + +## Current Rules + +- **AmericanSpelling.yml**: Enforces American English spelling (colour→color, organise→organize, etc.) +- **Acronyms.yml**: Validates acronym definitions and usage +- **Capitalization.yml**: Enforces proper capitalization for Mendix terms +- **ClickOn.yml**: Prohibits "click on" in favor of "click" +- **CompoundWords.yml**: Enforces proper compound word formatting +- **ConditionalAdverbs.yml**: Flags unnecessary conditional adverbs +- **Dashes.yml**: Enforces en dash usage in number ranges +- **Directions.yml**: Standardizes directional language +- **HeadingPunctuation.yml**: Prohibits end punctuation in headings (except question marks) +- **HeadingTitleCase.yml**: Enforces title case in headings +- **Inclusive.yml**: Flags non-inclusive language +- **LinkText.yml**: Prohibits generic link text like "click here" +- **ListIntroductions.yml**: Enforces en dashes in list item introductions (≤40 chars) +- **ProductNames.yml**: Enforces correct Mendix product names +- **SignIn.yml**: Standardizes "sign in" vs "sign-in" usage + +## Rule Types + +Vale supports several rule types (`extends`): + +- **substitution**: Simple find-and-replace (case-sensitive or insensitive) +- **existence**: Check if patterns exist (for prohibited terms) +- **occurrence**: Limit how often a term appears +- **repetition**: Flag repeated words +- **consistency**: Ensure consistent usage (e.g., "app" vs "application") +- **conditional**: Complex logic (if X then Y must follow) +- **capitalization**: Enforce capitalization patterns +- **readability**: Check reading level +- **spelling**: Custom dictionary + +## Severity Levels + +- `error`: Must fix +- `warning`: Should review +- `suggestion`: Nice to have + +## Adding New Rules + +Create a new `.yml` file in this directory: + +```yaml +# Mendix/MyRule.yml +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + 'bad term': 'good term' +``` + +## Testing Rules + +```bash +# Test against a specific file +.claude/bin/vale content/en/docs/path/to/file.md + +# Test only Mendix rules +.claude/bin/vale --config=".vale.ini" --filter="\.Mendix\." file.md + +# List all active rules +.claude/bin/vale ls-config +``` + +## Overriding Microsoft Rules + +In `.vale.ini`: + +```ini +# Disable a Microsoft rule +Microsoft.Contractions = NO + +# Change severity +Microsoft.Wordiness = warning +``` + +## Documentation + +- Vale docs: https://vale.sh/docs/ +- Rule examples: https://vale.sh/docs/topics/styles/ +- Microsoft package: https://github.com/errata-ai/Microsoft diff --git a/.vale/styles/Mendix/SignIn.yml b/.vale/styles/Mendix/SignIn.yml new file mode 100644 index 00000000000..a83c8b16c26 --- /dev/null +++ b/.vale/styles/Mendix/SignIn.yml @@ -0,0 +1,11 @@ +# Mendix custom rule: Use 'sign in' not 'log in' +# Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (sign in/sign out) +extends: substitution +message: "Use '%s' instead of '%s' (unless referring to UI button text)" +level: warning +ignorecase: true +swap: + 'log in': 'sign in' + 'log out': 'sign out' + 'login to': 'sign in to' + 'logout': 'sign out' diff --git a/.vale/styles/Microsoft/AMPM.yml b/.vale/styles/Microsoft/AMPM.yml new file mode 100644 index 00000000000..8b9fed162ab --- /dev/null +++ b/.vale/styles/Microsoft/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: Use 'AM' or 'PM' (preceded by a space). +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M' + - '\d{1,2} ?[ap]m' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.vale/styles/Microsoft/Accessibility.yml b/.vale/styles/Microsoft/Accessibility.yml new file mode 100644 index 00000000000..f5f48293921 --- /dev/null +++ b/.vale/styles/Microsoft/Accessibility.yml @@ -0,0 +1,30 @@ +extends: existence +message: "Don't use language (such as '%s') that defines people by their disability." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms +level: suggestion +ignorecase: true +tokens: + - a victim of + - able-bodied + - an epileptic + - birth defect + - crippled + - differently abled + - disabled + - dumb + - handicapped + - handicaps + - healthy person + - hearing-impaired + - lame + - maimed + - mentally handicapped + - missing a limb + - mute + - non-verbal + - normal person + - sight-impaired + - slow learner + - stricken with + - suffers from + - vision-impaired diff --git a/.vale/styles/Microsoft/Acronyms.yml b/.vale/styles/Microsoft/Acronyms.yml new file mode 100644 index 00000000000..308ff7c0ed8 --- /dev/null +++ b/.vale/styles/Microsoft/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "'%s' has no definition." +link: https://docs.microsoft.com/en-us/style-guide/acronyms +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.vale/styles/Microsoft/Adverbs.yml b/.vale/styles/Microsoft/Adverbs.yml new file mode 100644 index 00000000000..5619f99d8c9 --- /dev/null +++ b/.vale/styles/Microsoft/Adverbs.yml @@ -0,0 +1,272 @@ +extends: existence +message: "Remove '%s' if it's not important to the meaning of the statement." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences +ignorecase: true +level: warning +action: + name: remove +tokens: + - abnormally + - absentmindedly + - accidentally + - adventurously + - anxiously + - arrogantly + - awkwardly + - bashfully + - beautifully + - bitterly + - bleakly + - blindly + - blissfully + - boastfully + - boldly + - bravely + - briefly + - brightly + - briskly + - broadly + - busily + - calmly + - carefully + - carelessly + - cautiously + - cheerfully + - cleverly + - closely + - coaxingly + - colorfully + - continually + - coolly + - courageously + - crossly + - cruelly + - curiously + - daintily + - dearly + - deceivingly + - deeply + - defiantly + - deliberately + - delightfully + - diligently + - dimly + - doubtfully + - dreamily + - easily + - effectively + - elegantly + - energetically + - enormously + - enthusiastically + - excitedly + - extremely + - fairly + - faithfully + - famously + - ferociously + - fervently + - fiercely + - fondly + - foolishly + - fortunately + - frankly + - frantically + - freely + - frenetically + - frightfully + - furiously + - generally + - generously + - gently + - gladly + - gleefully + - gracefully + - gratefully + - greatly + - greedily + - happily + - hastily + - healthily + - heavily + - helplessly + - honestly + - hopelessly + - hungrily + - innocently + - inquisitively + - intensely + - intently + - interestingly + - inwardly + - irritably + - jaggedly + - jealously + - jovially + - joyfully + - joyously + - jubilantly + - judgmentally + - justly + - keenly + - kiddingly + - kindheartedly + - knavishly + - knowingly + - knowledgeably + - lazily + - lightly + - limply + - lively + - loftily + - longingly + - loosely + - loudly + - lovingly + - loyally + - madly + - majestically + - meaningfully + - mechanically + - merrily + - miserably + - mockingly + - mortally + - mysteriously + - naturally + - nearly + - neatly + - nervously + - nicely + - noisily + - obediently + - obnoxiously + - oddly + - offensively + - optimistically + - overconfidently + - painfully + - partially + - patiently + - perfectly + - playfully + - politely + - poorly + - positively + - potentially + - powerfully + - promptly + - properly + - punctually + - quaintly + - queasily + - queerly + - questionably + - quickly + - quietly + - quirkily + - quite + - quizzically + - randomly + - rapidly + - rarely + - readily + - really + - reassuringly + - recklessly + - regularly + - reluctantly + - repeatedly + - reproachfully + - restfully + - righteously + - rightfully + - rigidly + - roughly + - rudely + - safely + - scarcely + - scarily + - searchingly + - sedately + - seemingly + - selfishly + - separately + - seriously + - shakily + - sharply + - sheepishly + - shrilly + - shyly + - silently + - sleepily + - slowly + - smoothly + - softly + - solemnly + - solidly + - speedily + - stealthily + - sternly + - strictly + - suddenly + - supposedly + - surprisingly + - suspiciously + - sweetly + - swiftly + - sympathetically + - tenderly + - tensely + - terribly + - thankfully + - thoroughly + - thoughtfully + - tightly + - tremendously + - triumphantly + - truthfully + - ultimately + - unabashedly + - unaccountably + - unbearably + - unethically + - unexpectedly + - unfortunately + - unimpressively + - unnaturally + - unnecessarily + - urgently + - usefully + - uselessly + - utterly + - vacantly + - vaguely + - vainly + - valiantly + - vastly + - verbally + - very + - viciously + - victoriously + - violently + - vivaciously + - voluntarily + - warmly + - weakly + - wearily + - wetly + - wholly + - wildly + - willfully + - wisely + - woefully + - wonderfully + - worriedly + - yawningly + - yearningly + - yieldingly + - youthfully + - zealously + - zestfully + - zestily diff --git a/.vale/styles/Microsoft/Auto.yml b/.vale/styles/Microsoft/Auto.yml new file mode 100644 index 00000000000..4da4393530d --- /dev/null +++ b/.vale/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+' diff --git a/.vale/styles/Microsoft/Avoid.yml b/.vale/styles/Microsoft/Avoid.yml new file mode 100644 index 00000000000..dab7822c792 --- /dev/null +++ b/.vale/styles/Microsoft/Avoid.yml @@ -0,0 +1,14 @@ +extends: existence +message: "Don't use '%s'. See the A-Z word list for details." +# See the A-Z word list +link: https://docs.microsoft.com/en-us/style-guide +ignorecase: true +level: error +tokens: + - abortion + - and so on + - app(?:lication)?s? (?:developer|program) + - app(?:lication)? file + - backbone + - backend + - contiguous selection diff --git a/.vale/styles/Microsoft/Contractions.yml b/.vale/styles/Microsoft/Contractions.yml new file mode 100644 index 00000000000..8c81dcbce78 --- /dev/null +++ b/.vale/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 diff --git a/.vale/styles/Microsoft/Dashes.yml b/.vale/styles/Microsoft/Dashes.yml new file mode 100644 index 00000000000..72b05ba3e56 --- /dev/null +++ b/.vale/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' diff --git a/.vale/styles/Microsoft/DateFormat.yml b/.vale/styles/Microsoft/DateFormat.yml new file mode 100644 index 00000000000..196531394ac --- /dev/null +++ b/.vale/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}' diff --git a/.vale/styles/Microsoft/DateNumbers.yml b/.vale/styles/Microsoft/DateNumbers.yml new file mode 100644 index 00000000000..14d46747ca2 --- /dev/null +++ b/.vale/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 diff --git a/.vale/styles/Microsoft/DateOrder.yml b/.vale/styles/Microsoft/DateOrder.yml new file mode 100644 index 00000000000..12d69ba51e4 --- /dev/null +++ b/.vale/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' diff --git a/.vale/styles/Microsoft/Ellipses.yml b/.vale/styles/Microsoft/Ellipses.yml new file mode 100644 index 00000000000..320457a8bc5 --- /dev/null +++ b/.vale/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: + - '\.\.\.' diff --git a/.vale/styles/Microsoft/FirstPerson.yml b/.vale/styles/Microsoft/FirstPerson.yml new file mode 100644 index 00000000000..f58dea31420 --- /dev/null +++ b/.vale/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 diff --git a/.vale/styles/Microsoft/Foreign.yml b/.vale/styles/Microsoft/Foreign.yml new file mode 100644 index 00000000000..0d3d6002a9a --- /dev/null +++ b/.vale/styles/Microsoft/Foreign.yml @@ -0,0 +1,13 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words +ignorecase: true +level: error +nonword: true +action: + name: replace +swap: + '\b(?:eg|e\.g\.)[\s,]': for example + '\b(?:ie|i\.e\.)[\s,]': that is + '\b(?:viz\.)[\s,]': namely + '\b(?:ergo)[\s,]': therefore diff --git a/.vale/styles/Microsoft/Gender.yml b/.vale/styles/Microsoft/Gender.yml new file mode 100644 index 00000000000..47c08024797 --- /dev/null +++ b/.vale/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 diff --git a/.vale/styles/Microsoft/GenderBias.yml b/.vale/styles/Microsoft/GenderBias.yml new file mode 100644 index 00000000000..fc987b94e93 --- /dev/null +++ b/.vale/styles/Microsoft/GenderBias.yml @@ -0,0 +1,42 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: error +action: + name: replace +swap: + (?:alumna|alumnus): graduate + (?:alumnae|alumni): graduates + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + manpower: personnel + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + steward(?:ess)?: flight attendant + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/.vale/styles/Microsoft/GeneralURL.yml b/.vale/styles/Microsoft/GeneralURL.yml new file mode 100644 index 00000000000..dcef503d995 --- /dev/null +++ b/.vale/styles/Microsoft/GeneralURL.yml @@ -0,0 +1,11 @@ +extends: existence +message: "For a general audience, use 'address' rather than 'URL'." +link: https://docs.microsoft.com/en-us/style-guide/urls-web-addresses +level: warning +action: + name: replace + params: + - URL + - address +tokens: + - URL diff --git a/.vale/styles/Microsoft/HeadingAcronyms.yml b/.vale/styles/Microsoft/HeadingAcronyms.yml new file mode 100644 index 00000000000..9dc3b6c2de7 --- /dev/null +++ b/.vale/styles/Microsoft/HeadingAcronyms.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Avoid using acronyms in a title or heading." +link: https://docs.microsoft.com/en-us/style-guide/acronyms#be-careful-with-acronyms-in-titles-and-headings +level: warning +scope: heading +tokens: + - '[A-Z]{2,4}' diff --git a/.vale/styles/Microsoft/HeadingColons.yml b/.vale/styles/Microsoft/HeadingColons.yml new file mode 100644 index 00000000000..7013c391486 --- /dev/null +++ b/.vale/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]' diff --git a/.vale/styles/Microsoft/HeadingPunctuation.yml b/.vale/styles/Microsoft/HeadingPunctuation.yml new file mode 100644 index 00000000000..4954cb11aeb --- /dev/null +++ b/.vale/styles/Microsoft/HeadingPunctuation.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't use end punctuation in headings." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +nonword: true +level: warning +scope: heading +action: + name: edit + params: + - trim_right + - ".?!" +tokens: + - "[a-z][.?!]$" diff --git a/.vale/styles/Microsoft/Headings.yml b/.vale/styles/Microsoft/Headings.yml new file mode 100644 index 00000000000..63624edc1b4 --- /dev/null +++ b/.vale/styles/Microsoft/Headings.yml @@ -0,0 +1,28 @@ +extends: capitalization +message: "'%s' should use sentence-style capitalization." +link: https://docs.microsoft.com/en-us/style-guide/capitalization +level: suggestion +scope: heading +match: $sentence +indicators: + - ':' +exceptions: + - Azure + - CLI + - Code + - Cosmos + - Docker + - Emmet + - I + - Kubernetes + - Linux + - macOS + - Marketplace + - MongoDB + - REPL + - Studio + - TypeScript + - URLs + - Visual + - VS + - Windows diff --git a/.vale/styles/Microsoft/Hyphens.yml b/.vale/styles/Microsoft/Hyphens.yml new file mode 100644 index 00000000000..7e5731c9955 --- /dev/null +++ b/.vale/styles/Microsoft/Hyphens.yml @@ -0,0 +1,14 @@ +extends: existence +message: "'%s' doesn't need a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens +level: warning +ignorecase: false +nonword: true +action: + name: edit + params: + - regex + - "-" + - " " +tokens: + - '\b[^\s-]+ly-\w+\b' diff --git a/.vale/styles/Microsoft/Negative.yml b/.vale/styles/Microsoft/Negative.yml new file mode 100644 index 00000000000..d73221f5390 --- /dev/null +++ b/.vale/styles/Microsoft/Negative.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Form a negative number with an en dash, not a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +action: + name: edit + params: + - regex + - "-" + - "–" +tokens: + - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/.vale/styles/Microsoft/Ordinal.yml b/.vale/styles/Microsoft/Ordinal.yml new file mode 100644 index 00000000000..e3483e380c7 --- /dev/null +++ b/.vale/styles/Microsoft/Ordinal.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't add -ly to an ordinal number." +link: https://docs.microsoft.com/en-us/style-guide/numbers +level: error +action: + name: edit + params: + - trim + - ly +tokens: + - firstly + - secondly + - thirdly diff --git a/.vale/styles/Microsoft/OxfordComma.yml b/.vale/styles/Microsoft/OxfordComma.yml new file mode 100644 index 00000000000..493b55c3ce4 --- /dev/null +++ b/.vale/styles/Microsoft/OxfordComma.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas +scope: sentence +level: suggestion +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.vale/styles/Microsoft/Passive.yml b/.vale/styles/Microsoft/Passive.yml new file mode 100644 index 00000000000..102d377cac8 --- /dev/null +++ b/.vale/styles/Microsoft/Passive.yml @@ -0,0 +1,183 @@ +extends: existence +message: "'%s' looks like passive voice." +ignorecase: true +level: suggestion +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' + - awoken + - beat + - become + - been + - begun + - bent + - beset + - bet + - bid + - bidden + - bitten + - bled + - blown + - born + - bought + - bound + - bred + - broadcast + - broken + - brought + - built + - burnt + - burst + - cast + - caught + - chosen + - clung + - come + - cost + - crept + - cut + - dealt + - dived + - done + - drawn + - dreamt + - driven + - drunk + - dug + - eaten + - fallen + - fed + - felt + - fit + - fled + - flown + - flung + - forbidden + - foregone + - forgiven + - forgotten + - forsaken + - fought + - found + - frozen + - given + - gone + - gotten + - ground + - grown + - heard + - held + - hidden + - hit + - hung + - hurt + - kept + - knelt + - knit + - known + - laid + - lain + - leapt + - learnt + - led + - left + - lent + - let + - lighted + - lost + - made + - meant + - met + - misspelt + - mistaken + - mown + - overcome + - overdone + - overtaken + - overthrown + - paid + - pled + - proven + - put + - quit + - read + - rid + - ridden + - risen + - run + - rung + - said + - sat + - sawn + - seen + - sent + - set + - sewn + - shaken + - shaven + - shed + - shod + - shone + - shorn + - shot + - shown + - shrunk + - shut + - slain + - slept + - slid + - slit + - slung + - smitten + - sold + - sought + - sown + - sped + - spent + - spilt + - spit + - split + - spoken + - spread + - sprung + - spun + - stolen + - stood + - stridden + - striven + - struck + - strung + - stuck + - stung + - stunk + - sung + - sunk + - swept + - swollen + - sworn + - swum + - swung + - taken + - taught + - thought + - thrived + - thrown + - thrust + - told + - torn + - trodden + - understood + - upheld + - upset + - wed + - wept + - withheld + - withstood + - woken + - won + - worn + - wound + - woven + - written + - wrung diff --git a/.vale/styles/Microsoft/Percentages.yml b/.vale/styles/Microsoft/Percentages.yml new file mode 100644 index 00000000000..b68a7363f47 --- /dev/null +++ b/.vale/styles/Microsoft/Percentages.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use a numeral plus the units." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +tokens: + - '\b[a-zA-z]+\spercent\b' diff --git a/.vale/styles/Microsoft/Plurals.yml b/.vale/styles/Microsoft/Plurals.yml new file mode 100644 index 00000000000..1bb6660ade8 --- /dev/null +++ b/.vale/styles/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/.vale/styles/Microsoft/Quotes.yml b/.vale/styles/Microsoft/Quotes.yml new file mode 100644 index 00000000000..38f49760619 --- /dev/null +++ b/.vale/styles/Microsoft/Quotes.yml @@ -0,0 +1,7 @@ +extends: existence +message: 'Punctuation should be inside the quotes.' +link: https://docs.microsoft.com/en-us/style-guide/punctuation/quotation-marks +level: error +nonword: true +tokens: + - '["“][^"”“]+["”][.,]' diff --git a/.vale/styles/Microsoft/RangeTime.yml b/.vale/styles/Microsoft/RangeTime.yml new file mode 100644 index 00000000000..72d8bbfbe3e --- /dev/null +++ b/.vale/styles/Microsoft/RangeTime.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Use 'to' instead of a dash in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +action: + name: edit + params: + - regex + - "[-–]" + - "to" +tokens: + - '\b(?:AM|PM)\s?[-–]\s?.+(?:AM|PM)\b' diff --git a/.vale/styles/Microsoft/Semicolon.yml b/.vale/styles/Microsoft/Semicolon.yml new file mode 100644 index 00000000000..4d905467dd2 --- /dev/null +++ b/.vale/styles/Microsoft/Semicolon.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Try to simplify this sentence." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/semicolons +nonword: true +scope: sentence +level: suggestion +tokens: + - ';' diff --git a/.vale/styles/Microsoft/SentenceLength.yml b/.vale/styles/Microsoft/SentenceLength.yml new file mode 100644 index 00000000000..f248cf0513b --- /dev/null +++ b/.vale/styles/Microsoft/SentenceLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: "Try to keep sentences short (< 30 words)." +scope: sentence +level: suggestion +max: 30 +token: \b(\w+)\b + diff --git a/.vale/styles/Microsoft/Spacing.yml b/.vale/styles/Microsoft/Spacing.yml new file mode 100644 index 00000000000..bbd10e51df7 --- /dev/null +++ b/.vale/styles/Microsoft/Spacing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should have one space." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +level: error +nonword: true +tokens: + - '[a-z][.?!] {2,}[A-Z]' + - '[a-z][.?!][A-Z]' diff --git a/.vale/styles/Microsoft/Suspended.yml b/.vale/styles/Microsoft/Suspended.yml new file mode 100644 index 00000000000..7282e9c9cf5 --- /dev/null +++ b/.vale/styles/Microsoft/Suspended.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't use '%s' unless space is limited." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens +ignorecase: true +level: warning +tokens: + - '\w+- and \w+-' diff --git a/.vale/styles/Microsoft/Terms.yml b/.vale/styles/Microsoft/Terms.yml new file mode 100644 index 00000000000..65fca10aaa8 --- /dev/null +++ b/.vale/styles/Microsoft/Terms.yml @@ -0,0 +1,42 @@ +extends: substitution +message: "Prefer '%s' over '%s'." +# term preference should be based on microsoft style guide, such as +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter +level: warning +ignorecase: true +action: + name: replace +swap: + "(?:agent|virtual assistant|intelligent personal assistant)": personal digital assistant + "(?:assembler|machine language)": assembly language + "(?:drive C:|drive C>|C: drive)": drive C + "(?:internet bot|web robot)s?": bot(s) + "(?:microsoft cloud|the cloud)": cloud + "(?:mobile|smart) ?phone": phone + "24/7": every day + "audio(?:-| )book": audiobook + "back(?:-| )light": backlight + "chat ?bots?": chatbot(s) + adaptor: adapter + administrate: administer + afterwards: afterward + alphabetic: alphabetical + alphanumerical: alphanumeric + an URL: a URL + anti-aliasing: antialiasing + anti-malware: antimalware + anti-spyware: antispyware + anti-virus: antivirus + appendixes: appendices + artificial intelligence: AI + caap: CaaP + conversation-as-a-platform: conversation as a platform + eb: EB + gb: GB + gbps: Gbps + kb: KB + keypress: keystroke + mb: MB + pb: PB + tb: TB + zb: ZB diff --git a/.vale/styles/Microsoft/URLFormat.yml b/.vale/styles/Microsoft/URLFormat.yml new file mode 100644 index 00000000000..4e24aa59fe0 --- /dev/null +++ b/.vale/styles/Microsoft/URLFormat.yml @@ -0,0 +1,9 @@ +extends: substitution +message: Use 'of' (not 'for') to describe the relationship of the word URL to a resource. +ignorecase: true +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/url +level: suggestion +action: + name: replace +swap: + URL for: URL of diff --git a/.vale/styles/Microsoft/Units.yml b/.vale/styles/Microsoft/Units.yml new file mode 100644 index 00000000000..f062418ee0d --- /dev/null +++ b/.vale/styles/Microsoft/Units.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Don't spell out the number in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/units-of-measure-terms +level: error +raw: + - '[a-zA-Z]+\s' +tokens: + - '(?:centi|milli)?meters' + - '(?:kilo)?grams' + - '(?:kilo)?meters' + - '(?:mega)?pixels' + - cm + - inches + - lb + - miles + - pounds diff --git a/.vale/styles/Microsoft/Vocab.yml b/.vale/styles/Microsoft/Vocab.yml new file mode 100644 index 00000000000..eebe97b15ee --- /dev/null +++ b/.vale/styles/Microsoft/Vocab.yml @@ -0,0 +1,25 @@ +extends: existence +message: "Verify your use of '%s' with the A-Z word list." +link: 'https://docs.microsoft.com/en-us/style-guide' +level: suggestion +ignorecase: true +tokens: + - above + - accessible + - actionable + - against + - alarm + - alert + - alias + - allows? + - and/or + - as well as + - assure + - author + - avg + - beta + - ensure + - he + - insure + - sample + - she diff --git a/.vale/styles/Microsoft/We.yml b/.vale/styles/Microsoft/We.yml new file mode 100644 index 00000000000..97c901c1bae --- /dev/null +++ b/.vale/styles/Microsoft/We.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Try to avoid using first-person plural like '%s'." +link: https://docs.microsoft.com/en-us/style-guide/grammar/person#avoid-first-person-plural +level: warning +ignorecase: true +tokens: + - we + - we'(?:ve|re) + - ours? + - us + - let's diff --git a/.vale/styles/Microsoft/Wordiness.yml b/.vale/styles/Microsoft/Wordiness.yml new file mode 100644 index 00000000000..8a4fea74833 --- /dev/null +++ b/.vale/styles/Microsoft/Wordiness.yml @@ -0,0 +1,127 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences +ignorecase: true +level: suggestion +action: + name: replace +swap: + "sufficient number(?: of)?": enough + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell + (?:previous|prior) to: before + (?:utilize|make use of): use + a (?:large)? majority of: most + a (?:large)? number of: many + a myriad of: myriad + adversely impact: hurt + all across: across + all of a sudden: suddenly + all of these: these + all of(?! a sudden| these): all + all-time record: record + almost all: most + almost never: seldom + along the lines of: similar to + an adequate number of: enough + an appreciable number of: many + an estimated: about + any and all: all + are in agreement: agree + as a matter of fact: in fact + as a means of: to + as a result of: because of + as of yet: yet + as per: per + at a later date: later + at all times: always + at the present time: now + at this point in time: at this point + based in large part on: based on + based on the fact that: because + basic necessity: necessity + because of the fact that: because + came to a realization: realized + came to an abrupt end: ended abruptly + carry out an evaluation of: evaluate + close down: close + closed down: closed + complete stranger: stranger + completely separate: separate + concerning the matter of: regarding + conduct a review of: review + conduct an investigation: investigate + conduct experiments: experiment + continue on: continue + despite the fact that: although + disappear from sight: disappear + doomed to fail: doomed + drag and drop: drag + drag-and-drop: drag + due to the fact that: because + during the period of: during + during the time that: while + emergency situation: emergency + establish connectivity: connect + except when: unless + excessive number: too many + extend an invitation: invite + fall down: fall + fell down: fell + for the duration of: during + gather together: gather + has the ability to: can + has the capacity to: can + has the opportunity to: could + hold a meeting: meet + if this is not the case: if not + in a careful manner: carefully + in a thoughtful manner: thoughtfully + in a timely manner: timely + in addition: also + in an effort to: to + in between: between + in lieu of: instead of + in many cases: often + in most cases: usually + in order to: to + in some cases: sometimes + in spite of the fact that: although + in spite of: despite + in the (?:very)? near future: soon + in the event that: if + in the neighborhood of: roughly + in the vicinity of: close to + it would appear that: apparently + lift up: lift + made reference to: referred to + make reference to: refer to + mix together: mix + none at all: none + not in a position to: unable + not possible: impossible + of major importance: important + perform an assessment of: assess + pertaining to: about + place an order: order + plays a key role in: is essential to + present time: now + readily apparent: apparent + some of the: some + span across: span + subsequent to: after + successfully complete: complete + take action: act + take into account: consider + the question as to whether: whether + there is no doubt but that: doubtless + this day and age: this age + this is a subject that: this subject + time (?:frame|period): time + under the provisions of: under + until such time as: until + used for fuel purposes: used for fuel + whether or not: whether + with regard to: regarding + with the exception of: except for diff --git a/.vale/styles/Microsoft/meta.json b/.vale/styles/Microsoft/meta.json new file mode 100644 index 00000000000..297719bbbff --- /dev/null +++ b/.vale/styles/Microsoft/meta.json @@ -0,0 +1,4 @@ +{ + "feed": "https://github.com/errata-ai/Microsoft/releases.atom", + "vale_version": ">=1.0.0" +} From e3afa817a05b4ea32d72e8d08c079d0cdd0abc17 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Tue, 26 May 2026 16:02:47 +0200 Subject: [PATCH 02/19] Disable Vale check on some files --- CLAUDE.md | 1 + .../docs/community-tools/contribute-to-mendix-docs/icon-demo.md | 1 + .../contribute-to-mendix-docs/markdown-shortcodes.md | 1 + .../contribute-to-mendix-docs/style-guide/grammar-formatting.md | 1 + .../style-guide/product-naming-guide.md | 1 + .../contribute-to-mendix-docs/style-guide/terminology.md | 1 + 6 files changed, 6 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index f8f16033de0..3aff429caa7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,6 @@ # Mendix Documentation Repository + **Your role**: Edit and review Markdown documentation files under `content/en/docs/` following the style guidance and project-specific conventions below. diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/icon-demo.md b/content/en/docs/community-tools/contribute-to-mendix-docs/icon-demo.md index 8507c9a59ad..7731ed7491a 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/icon-demo.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/icon-demo.md @@ -6,6 +6,7 @@ description: "Demo file for SVG icon shortcodes." draft: true --- + ## Introduction diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/markdown-shortcodes.md b/content/en/docs/community-tools/contribute-to-mendix-docs/markdown-shortcodes.md index 46faf6bf167..40861d9798f 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/markdown-shortcodes.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/markdown-shortcodes.md @@ -6,6 +6,7 @@ description: "Various test cases and examples for Markdown and shortcodes. Use t linktitle: "Shortcodes, Markdown, and HTML" --- + ## Introduction diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md index c682c5f2a24..be61b01b8fc 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md @@ -4,6 +4,7 @@ url: /community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/ weight: 20 description: "Guidelines on grammar, formatting, capitalization, punctuation, lists, headings, and other writing conventions for Mendix documentation." --- + ## Acronyms and Initialisms diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md index 0ebc4b0222c..402b95dc42c 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md @@ -4,6 +4,7 @@ url: /community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide weight: 100 description: "Guidelines on usage, capitalization, and spelling for Mendix product names and terms, including main products and other Mendix-specific terminology." --- + ## Purpose of This Guide diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md index 7951329236b..f5802b264da 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md @@ -4,6 +4,7 @@ url: /community-tools/contribute-to-mendix-docs/style-guide/terminology/ weight: 30 description: "Usage guidelines for general terminology in Mendix documentation, covering technical terms, formatting conventions, word choice, and inclusive language." --- + ## How to Use This Section From 50c52b2db88ce0d0f0232b241bbda9331c82b7bd Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Tue, 26 May 2026 16:55:50 +0200 Subject: [PATCH 03/19] Gitignore the Vale Microsoft styles --- .gitignore | 1 + .vale/styles/Microsoft/AMPM.yml | 9 - .vale/styles/Microsoft/Accessibility.yml | 30 -- .vale/styles/Microsoft/Acronyms.yml | 64 ----- .vale/styles/Microsoft/Adverbs.yml | 272 ------------------ .vale/styles/Microsoft/Auto.yml | 11 - .vale/styles/Microsoft/Avoid.yml | 14 - .vale/styles/Microsoft/Contractions.yml | 50 ---- .vale/styles/Microsoft/Dashes.yml | 13 - .vale/styles/Microsoft/DateFormat.yml | 8 - .vale/styles/Microsoft/DateNumbers.yml | 40 --- .vale/styles/Microsoft/DateOrder.yml | 8 - .vale/styles/Microsoft/Ellipses.yml | 9 - .vale/styles/Microsoft/FirstPerson.yml | 16 -- .vale/styles/Microsoft/Foreign.yml | 13 - .vale/styles/Microsoft/Gender.yml | 8 - .vale/styles/Microsoft/GenderBias.yml | 42 --- .vale/styles/Microsoft/GeneralURL.yml | 11 - .vale/styles/Microsoft/HeadingAcronyms.yml | 7 - .vale/styles/Microsoft/HeadingColons.yml | 8 - .vale/styles/Microsoft/HeadingPunctuation.yml | 13 - .vale/styles/Microsoft/Headings.yml | 28 -- .vale/styles/Microsoft/Hyphens.yml | 14 - .vale/styles/Microsoft/Negative.yml | 13 - .vale/styles/Microsoft/Ordinal.yml | 13 - .vale/styles/Microsoft/OxfordComma.yml | 8 - .vale/styles/Microsoft/Passive.yml | 183 ------------ .vale/styles/Microsoft/Percentages.yml | 7 - .vale/styles/Microsoft/Plurals.yml | 7 - .vale/styles/Microsoft/Quotes.yml | 7 - .vale/styles/Microsoft/RangeTime.yml | 13 - .vale/styles/Microsoft/Semicolon.yml | 8 - .vale/styles/Microsoft/SentenceLength.yml | 7 - .vale/styles/Microsoft/Spacing.yml | 8 - .vale/styles/Microsoft/Suspended.yml | 7 - .vale/styles/Microsoft/Terms.yml | 42 --- .vale/styles/Microsoft/URLFormat.yml | 9 - .vale/styles/Microsoft/Units.yml | 16 -- .vale/styles/Microsoft/Vocab.yml | 25 -- .vale/styles/Microsoft/We.yml | 11 - .vale/styles/Microsoft/Wordiness.yml | 127 -------- .vale/styles/Microsoft/meta.json | 4 - 42 files changed, 1 insertion(+), 1203 deletions(-) delete mode 100644 .vale/styles/Microsoft/AMPM.yml delete mode 100644 .vale/styles/Microsoft/Accessibility.yml delete mode 100644 .vale/styles/Microsoft/Acronyms.yml delete mode 100644 .vale/styles/Microsoft/Adverbs.yml delete mode 100644 .vale/styles/Microsoft/Auto.yml delete mode 100644 .vale/styles/Microsoft/Avoid.yml delete mode 100644 .vale/styles/Microsoft/Contractions.yml delete mode 100644 .vale/styles/Microsoft/Dashes.yml delete mode 100644 .vale/styles/Microsoft/DateFormat.yml delete mode 100644 .vale/styles/Microsoft/DateNumbers.yml delete mode 100644 .vale/styles/Microsoft/DateOrder.yml delete mode 100644 .vale/styles/Microsoft/Ellipses.yml delete mode 100644 .vale/styles/Microsoft/FirstPerson.yml delete mode 100644 .vale/styles/Microsoft/Foreign.yml delete mode 100644 .vale/styles/Microsoft/Gender.yml delete mode 100644 .vale/styles/Microsoft/GenderBias.yml delete mode 100644 .vale/styles/Microsoft/GeneralURL.yml delete mode 100644 .vale/styles/Microsoft/HeadingAcronyms.yml delete mode 100644 .vale/styles/Microsoft/HeadingColons.yml delete mode 100644 .vale/styles/Microsoft/HeadingPunctuation.yml delete mode 100644 .vale/styles/Microsoft/Headings.yml delete mode 100644 .vale/styles/Microsoft/Hyphens.yml delete mode 100644 .vale/styles/Microsoft/Negative.yml delete mode 100644 .vale/styles/Microsoft/Ordinal.yml delete mode 100644 .vale/styles/Microsoft/OxfordComma.yml delete mode 100644 .vale/styles/Microsoft/Passive.yml delete mode 100644 .vale/styles/Microsoft/Percentages.yml delete mode 100644 .vale/styles/Microsoft/Plurals.yml delete mode 100644 .vale/styles/Microsoft/Quotes.yml delete mode 100644 .vale/styles/Microsoft/RangeTime.yml delete mode 100644 .vale/styles/Microsoft/Semicolon.yml delete mode 100644 .vale/styles/Microsoft/SentenceLength.yml delete mode 100644 .vale/styles/Microsoft/Spacing.yml delete mode 100644 .vale/styles/Microsoft/Suspended.yml delete mode 100644 .vale/styles/Microsoft/Terms.yml delete mode 100644 .vale/styles/Microsoft/URLFormat.yml delete mode 100644 .vale/styles/Microsoft/Units.yml delete mode 100644 .vale/styles/Microsoft/Vocab.yml delete mode 100644 .vale/styles/Microsoft/We.yml delete mode 100644 .vale/styles/Microsoft/Wordiness.yml delete mode 100644 .vale/styles/Microsoft/meta.json diff --git a/.gitignore b/.gitignore index 5a8ed970dd5..7a90cada5d8 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ hugo.exe /.claude/audit.log /.claude/settings.local.json /.mcp.json +/.vale/styles/Microsoft/ # For Mac users .DS_Store diff --git a/.vale/styles/Microsoft/AMPM.yml b/.vale/styles/Microsoft/AMPM.yml deleted file mode 100644 index 8b9fed162ab..00000000000 --- a/.vale/styles/Microsoft/AMPM.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: Use 'AM' or 'PM' (preceded by a space). -link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms -level: error -nonword: true -tokens: - - '\d{1,2}[AP]M' - - '\d{1,2} ?[ap]m' - - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.vale/styles/Microsoft/Accessibility.yml b/.vale/styles/Microsoft/Accessibility.yml deleted file mode 100644 index f5f48293921..00000000000 --- a/.vale/styles/Microsoft/Accessibility.yml +++ /dev/null @@ -1,30 +0,0 @@ -extends: existence -message: "Don't use language (such as '%s') that defines people by their disability." -link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms -level: suggestion -ignorecase: true -tokens: - - a victim of - - able-bodied - - an epileptic - - birth defect - - crippled - - differently abled - - disabled - - dumb - - handicapped - - handicaps - - healthy person - - hearing-impaired - - lame - - maimed - - mentally handicapped - - missing a limb - - mute - - non-verbal - - normal person - - sight-impaired - - slow learner - - stricken with - - suffers from - - vision-impaired diff --git a/.vale/styles/Microsoft/Acronyms.yml b/.vale/styles/Microsoft/Acronyms.yml deleted file mode 100644 index 308ff7c0ed8..00000000000 --- a/.vale/styles/Microsoft/Acronyms.yml +++ /dev/null @@ -1,64 +0,0 @@ -extends: conditional -message: "'%s' has no definition." -link: https://docs.microsoft.com/en-us/style-guide/acronyms -level: suggestion -ignorecase: false -# Ensures that the existence of 'first' implies the existence of 'second'. -first: '\b([A-Z]{3,5})\b' -second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' -# ... with the exception of these: -exceptions: - - API - - ASP - - CLI - - CPU - - CSS - - CSV - - DEBUG - - DOM - - DPI - - FAQ - - GCC - - GDB - - GET - - GPU - - GTK - - GUI - - HTML - - HTTP - - HTTPS - - IDE - - JAR - - JSON - - JSX - - LESS - - LLDB - - NET - - NOTE - - NVDA - - OSS - - PATH - - PDF - - PHP - - POST - - RAM - - REPL - - RSA - - SCM - - SCSS - - SDK - - SQL - - SSH - - SSL - - SVG - - TBD - - TCP - - TODO - - URI - - URL - - USB - - UTF - - XML - - XSS - - YAML - - ZIP diff --git a/.vale/styles/Microsoft/Adverbs.yml b/.vale/styles/Microsoft/Adverbs.yml deleted file mode 100644 index 5619f99d8c9..00000000000 --- a/.vale/styles/Microsoft/Adverbs.yml +++ /dev/null @@ -1,272 +0,0 @@ -extends: existence -message: "Remove '%s' if it's not important to the meaning of the statement." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences -ignorecase: true -level: warning -action: - name: remove -tokens: - - abnormally - - absentmindedly - - accidentally - - adventurously - - anxiously - - arrogantly - - awkwardly - - bashfully - - beautifully - - bitterly - - bleakly - - blindly - - blissfully - - boastfully - - boldly - - bravely - - briefly - - brightly - - briskly - - broadly - - busily - - calmly - - carefully - - carelessly - - cautiously - - cheerfully - - cleverly - - closely - - coaxingly - - colorfully - - continually - - coolly - - courageously - - crossly - - cruelly - - curiously - - daintily - - dearly - - deceivingly - - deeply - - defiantly - - deliberately - - delightfully - - diligently - - dimly - - doubtfully - - dreamily - - easily - - effectively - - elegantly - - energetically - - enormously - - enthusiastically - - excitedly - - extremely - - fairly - - faithfully - - famously - - ferociously - - fervently - - fiercely - - fondly - - foolishly - - fortunately - - frankly - - frantically - - freely - - frenetically - - frightfully - - furiously - - generally - - generously - - gently - - gladly - - gleefully - - gracefully - - gratefully - - greatly - - greedily - - happily - - hastily - - healthily - - heavily - - helplessly - - honestly - - hopelessly - - hungrily - - innocently - - inquisitively - - intensely - - intently - - interestingly - - inwardly - - irritably - - jaggedly - - jealously - - jovially - - joyfully - - joyously - - jubilantly - - judgmentally - - justly - - keenly - - kiddingly - - kindheartedly - - knavishly - - knowingly - - knowledgeably - - lazily - - lightly - - limply - - lively - - loftily - - longingly - - loosely - - loudly - - lovingly - - loyally - - madly - - majestically - - meaningfully - - mechanically - - merrily - - miserably - - mockingly - - mortally - - mysteriously - - naturally - - nearly - - neatly - - nervously - - nicely - - noisily - - obediently - - obnoxiously - - oddly - - offensively - - optimistically - - overconfidently - - painfully - - partially - - patiently - - perfectly - - playfully - - politely - - poorly - - positively - - potentially - - powerfully - - promptly - - properly - - punctually - - quaintly - - queasily - - queerly - - questionably - - quickly - - quietly - - quirkily - - quite - - quizzically - - randomly - - rapidly - - rarely - - readily - - really - - reassuringly - - recklessly - - regularly - - reluctantly - - repeatedly - - reproachfully - - restfully - - righteously - - rightfully - - rigidly - - roughly - - rudely - - safely - - scarcely - - scarily - - searchingly - - sedately - - seemingly - - selfishly - - separately - - seriously - - shakily - - sharply - - sheepishly - - shrilly - - shyly - - silently - - sleepily - - slowly - - smoothly - - softly - - solemnly - - solidly - - speedily - - stealthily - - sternly - - strictly - - suddenly - - supposedly - - surprisingly - - suspiciously - - sweetly - - swiftly - - sympathetically - - tenderly - - tensely - - terribly - - thankfully - - thoroughly - - thoughtfully - - tightly - - tremendously - - triumphantly - - truthfully - - ultimately - - unabashedly - - unaccountably - - unbearably - - unethically - - unexpectedly - - unfortunately - - unimpressively - - unnaturally - - unnecessarily - - urgently - - usefully - - uselessly - - utterly - - vacantly - - vaguely - - vainly - - valiantly - - vastly - - verbally - - very - - viciously - - victoriously - - violently - - vivaciously - - voluntarily - - warmly - - weakly - - wearily - - wetly - - wholly - - wildly - - willfully - - wisely - - woefully - - wonderfully - - worriedly - - yawningly - - yearningly - - yieldingly - - youthfully - - zealously - - zestfully - - zestily diff --git a/.vale/styles/Microsoft/Auto.yml b/.vale/styles/Microsoft/Auto.yml deleted file mode 100644 index 4da4393530d..00000000000 --- a/.vale/styles/Microsoft/Auto.yml +++ /dev/null @@ -1,11 +0,0 @@ -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+' diff --git a/.vale/styles/Microsoft/Avoid.yml b/.vale/styles/Microsoft/Avoid.yml deleted file mode 100644 index dab7822c792..00000000000 --- a/.vale/styles/Microsoft/Avoid.yml +++ /dev/null @@ -1,14 +0,0 @@ -extends: existence -message: "Don't use '%s'. See the A-Z word list for details." -# See the A-Z word list -link: https://docs.microsoft.com/en-us/style-guide -ignorecase: true -level: error -tokens: - - abortion - - and so on - - app(?:lication)?s? (?:developer|program) - - app(?:lication)? file - - backbone - - backend - - contiguous selection diff --git a/.vale/styles/Microsoft/Contractions.yml b/.vale/styles/Microsoft/Contractions.yml deleted file mode 100644 index 8c81dcbce78..00000000000 --- a/.vale/styles/Microsoft/Contractions.yml +++ /dev/null @@ -1,50 +0,0 @@ -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 diff --git a/.vale/styles/Microsoft/Dashes.yml b/.vale/styles/Microsoft/Dashes.yml deleted file mode 100644 index 72b05ba3e56..00000000000 --- a/.vale/styles/Microsoft/Dashes.yml +++ /dev/null @@ -1,13 +0,0 @@ -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' diff --git a/.vale/styles/Microsoft/DateFormat.yml b/.vale/styles/Microsoft/DateFormat.yml deleted file mode 100644 index 196531394ac..00000000000 --- a/.vale/styles/Microsoft/DateFormat.yml +++ /dev/null @@ -1,8 +0,0 @@ -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}' diff --git a/.vale/styles/Microsoft/DateNumbers.yml b/.vale/styles/Microsoft/DateNumbers.yml deleted file mode 100644 index 14d46747ca2..00000000000 --- a/.vale/styles/Microsoft/DateNumbers.yml +++ /dev/null @@ -1,40 +0,0 @@ -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 diff --git a/.vale/styles/Microsoft/DateOrder.yml b/.vale/styles/Microsoft/DateOrder.yml deleted file mode 100644 index 12d69ba51e4..00000000000 --- a/.vale/styles/Microsoft/DateOrder.yml +++ /dev/null @@ -1,8 +0,0 @@ -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' diff --git a/.vale/styles/Microsoft/Ellipses.yml b/.vale/styles/Microsoft/Ellipses.yml deleted file mode 100644 index 320457a8bc5..00000000000 --- a/.vale/styles/Microsoft/Ellipses.yml +++ /dev/null @@ -1,9 +0,0 @@ -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: - - '\.\.\.' diff --git a/.vale/styles/Microsoft/FirstPerson.yml b/.vale/styles/Microsoft/FirstPerson.yml deleted file mode 100644 index f58dea31420..00000000000 --- a/.vale/styles/Microsoft/FirstPerson.yml +++ /dev/null @@ -1,16 +0,0 @@ -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 diff --git a/.vale/styles/Microsoft/Foreign.yml b/.vale/styles/Microsoft/Foreign.yml deleted file mode 100644 index 0d3d6002a9a..00000000000 --- a/.vale/styles/Microsoft/Foreign.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words -ignorecase: true -level: error -nonword: true -action: - name: replace -swap: - '\b(?:eg|e\.g\.)[\s,]': for example - '\b(?:ie|i\.e\.)[\s,]': that is - '\b(?:viz\.)[\s,]': namely - '\b(?:ergo)[\s,]': therefore diff --git a/.vale/styles/Microsoft/Gender.yml b/.vale/styles/Microsoft/Gender.yml deleted file mode 100644 index 47c08024797..00000000000 --- a/.vale/styles/Microsoft/Gender.yml +++ /dev/null @@ -1,8 +0,0 @@ -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 diff --git a/.vale/styles/Microsoft/GenderBias.yml b/.vale/styles/Microsoft/GenderBias.yml deleted file mode 100644 index fc987b94e93..00000000000 --- a/.vale/styles/Microsoft/GenderBias.yml +++ /dev/null @@ -1,42 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of '%s'." -ignorecase: true -level: error -action: - name: replace -swap: - (?:alumna|alumnus): graduate - (?:alumnae|alumni): graduates - air(?:m[ae]n|wom[ae]n): pilot(s) - anchor(?:m[ae]n|wom[ae]n): anchor(s) - authoress: author - camera(?:m[ae]n|wom[ae]n): camera operator(s) - door(?:m[ae]|wom[ae]n): concierge(s) - draft(?:m[ae]n|wom[ae]n): drafter(s) - fire(?:m[ae]n|wom[ae]n): firefighter(s) - fisher(?:m[ae]n|wom[ae]n): fisher(s) - fresh(?:m[ae]n|wom[ae]n): first-year student(s) - garbage(?:m[ae]n|wom[ae]n): waste collector(s) - lady lawyer: lawyer - ladylike: courteous - mail(?:m[ae]n|wom[ae]n): mail carriers - man and wife: husband and wife - man enough: strong enough - mankind: human kind - manmade: manufactured - manpower: personnel - middle(?:m[ae]n|wom[ae]n): intermediary - news(?:m[ae]n|wom[ae]n): journalist(s) - ombuds(?:man|woman): ombuds - oneupmanship: upstaging - poetess: poet - police(?:m[ae]n|wom[ae]n): police officer(s) - repair(?:m[ae]n|wom[ae]n): technician(s) - sales(?:m[ae]n|wom[ae]n): salesperson or sales people - service(?:m[ae]n|wom[ae]n): soldier(s) - steward(?:ess)?: flight attendant - tribes(?:m[ae]n|wom[ae]n): tribe member(s) - waitress: waiter - woman doctor: doctor - woman scientist[s]?: scientist(s) - work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/.vale/styles/Microsoft/GeneralURL.yml b/.vale/styles/Microsoft/GeneralURL.yml deleted file mode 100644 index dcef503d995..00000000000 --- a/.vale/styles/Microsoft/GeneralURL.yml +++ /dev/null @@ -1,11 +0,0 @@ -extends: existence -message: "For a general audience, use 'address' rather than 'URL'." -link: https://docs.microsoft.com/en-us/style-guide/urls-web-addresses -level: warning -action: - name: replace - params: - - URL - - address -tokens: - - URL diff --git a/.vale/styles/Microsoft/HeadingAcronyms.yml b/.vale/styles/Microsoft/HeadingAcronyms.yml deleted file mode 100644 index 9dc3b6c2de7..00000000000 --- a/.vale/styles/Microsoft/HeadingAcronyms.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Avoid using acronyms in a title or heading." -link: https://docs.microsoft.com/en-us/style-guide/acronyms#be-careful-with-acronyms-in-titles-and-headings -level: warning -scope: heading -tokens: - - '[A-Z]{2,4}' diff --git a/.vale/styles/Microsoft/HeadingColons.yml b/.vale/styles/Microsoft/HeadingColons.yml deleted file mode 100644 index 7013c391486..00000000000 --- a/.vale/styles/Microsoft/HeadingColons.yml +++ /dev/null @@ -1,8 +0,0 @@ -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]' diff --git a/.vale/styles/Microsoft/HeadingPunctuation.yml b/.vale/styles/Microsoft/HeadingPunctuation.yml deleted file mode 100644 index 4954cb11aeb..00000000000 --- a/.vale/styles/Microsoft/HeadingPunctuation.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Don't use end punctuation in headings." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods -nonword: true -level: warning -scope: heading -action: - name: edit - params: - - trim_right - - ".?!" -tokens: - - "[a-z][.?!]$" diff --git a/.vale/styles/Microsoft/Headings.yml b/.vale/styles/Microsoft/Headings.yml deleted file mode 100644 index 63624edc1b4..00000000000 --- a/.vale/styles/Microsoft/Headings.yml +++ /dev/null @@ -1,28 +0,0 @@ -extends: capitalization -message: "'%s' should use sentence-style capitalization." -link: https://docs.microsoft.com/en-us/style-guide/capitalization -level: suggestion -scope: heading -match: $sentence -indicators: - - ':' -exceptions: - - Azure - - CLI - - Code - - Cosmos - - Docker - - Emmet - - I - - Kubernetes - - Linux - - macOS - - Marketplace - - MongoDB - - REPL - - Studio - - TypeScript - - URLs - - Visual - - VS - - Windows diff --git a/.vale/styles/Microsoft/Hyphens.yml b/.vale/styles/Microsoft/Hyphens.yml deleted file mode 100644 index 7e5731c9955..00000000000 --- a/.vale/styles/Microsoft/Hyphens.yml +++ /dev/null @@ -1,14 +0,0 @@ -extends: existence -message: "'%s' doesn't need a hyphen." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens -level: warning -ignorecase: false -nonword: true -action: - name: edit - params: - - regex - - "-" - - " " -tokens: - - '\b[^\s-]+ly-\w+\b' diff --git a/.vale/styles/Microsoft/Negative.yml b/.vale/styles/Microsoft/Negative.yml deleted file mode 100644 index d73221f5390..00000000000 --- a/.vale/styles/Microsoft/Negative.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Form a negative number with an en dash, not a hyphen." -link: https://docs.microsoft.com/en-us/style-guide/numbers -nonword: true -level: error -action: - name: edit - params: - - regex - - "-" - - "–" -tokens: - - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/.vale/styles/Microsoft/Ordinal.yml b/.vale/styles/Microsoft/Ordinal.yml deleted file mode 100644 index e3483e380c7..00000000000 --- a/.vale/styles/Microsoft/Ordinal.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Don't add -ly to an ordinal number." -link: https://docs.microsoft.com/en-us/style-guide/numbers -level: error -action: - name: edit - params: - - trim - - ly -tokens: - - firstly - - secondly - - thirdly diff --git a/.vale/styles/Microsoft/OxfordComma.yml b/.vale/styles/Microsoft/OxfordComma.yml deleted file mode 100644 index 493b55c3ce4..00000000000 --- a/.vale/styles/Microsoft/OxfordComma.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "Use the Oxford comma in '%s'." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas -scope: sentence -level: suggestion -nonword: true -tokens: - - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.vale/styles/Microsoft/Passive.yml b/.vale/styles/Microsoft/Passive.yml deleted file mode 100644 index 102d377cac8..00000000000 --- a/.vale/styles/Microsoft/Passive.yml +++ /dev/null @@ -1,183 +0,0 @@ -extends: existence -message: "'%s' looks like passive voice." -ignorecase: true -level: suggestion -raw: - - \b(am|are|were|being|is|been|was|be)\b\s* -tokens: - - '[\w]+ed' - - awoken - - beat - - become - - been - - begun - - bent - - beset - - bet - - bid - - bidden - - bitten - - bled - - blown - - born - - bought - - bound - - bred - - broadcast - - broken - - brought - - built - - burnt - - burst - - cast - - caught - - chosen - - clung - - come - - cost - - crept - - cut - - dealt - - dived - - done - - drawn - - dreamt - - driven - - drunk - - dug - - eaten - - fallen - - fed - - felt - - fit - - fled - - flown - - flung - - forbidden - - foregone - - forgiven - - forgotten - - forsaken - - fought - - found - - frozen - - given - - gone - - gotten - - ground - - grown - - heard - - held - - hidden - - hit - - hung - - hurt - - kept - - knelt - - knit - - known - - laid - - lain - - leapt - - learnt - - led - - left - - lent - - let - - lighted - - lost - - made - - meant - - met - - misspelt - - mistaken - - mown - - overcome - - overdone - - overtaken - - overthrown - - paid - - pled - - proven - - put - - quit - - read - - rid - - ridden - - risen - - run - - rung - - said - - sat - - sawn - - seen - - sent - - set - - sewn - - shaken - - shaven - - shed - - shod - - shone - - shorn - - shot - - shown - - shrunk - - shut - - slain - - slept - - slid - - slit - - slung - - smitten - - sold - - sought - - sown - - sped - - spent - - spilt - - spit - - split - - spoken - - spread - - sprung - - spun - - stolen - - stood - - stridden - - striven - - struck - - strung - - stuck - - stung - - stunk - - sung - - sunk - - swept - - swollen - - sworn - - swum - - swung - - taken - - taught - - thought - - thrived - - thrown - - thrust - - told - - torn - - trodden - - understood - - upheld - - upset - - wed - - wept - - withheld - - withstood - - woken - - won - - worn - - wound - - woven - - written - - wrung diff --git a/.vale/styles/Microsoft/Percentages.yml b/.vale/styles/Microsoft/Percentages.yml deleted file mode 100644 index b68a7363f47..00000000000 --- a/.vale/styles/Microsoft/Percentages.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Use a numeral plus the units." -link: https://docs.microsoft.com/en-us/style-guide/numbers -nonword: true -level: error -tokens: - - '\b[a-zA-z]+\spercent\b' diff --git a/.vale/styles/Microsoft/Plurals.yml b/.vale/styles/Microsoft/Plurals.yml deleted file mode 100644 index 1bb6660ade8..00000000000 --- a/.vale/styles/Microsoft/Plurals.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Don't add '%s' to a singular noun. Use plural instead." -ignorecase: true -level: error -link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es -raw: - - '\(s\)|\(es\)' diff --git a/.vale/styles/Microsoft/Quotes.yml b/.vale/styles/Microsoft/Quotes.yml deleted file mode 100644 index 38f49760619..00000000000 --- a/.vale/styles/Microsoft/Quotes.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: 'Punctuation should be inside the quotes.' -link: https://docs.microsoft.com/en-us/style-guide/punctuation/quotation-marks -level: error -nonword: true -tokens: - - '["“][^"”“]+["”][.,]' diff --git a/.vale/styles/Microsoft/RangeTime.yml b/.vale/styles/Microsoft/RangeTime.yml deleted file mode 100644 index 72d8bbfbe3e..00000000000 --- a/.vale/styles/Microsoft/RangeTime.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Use 'to' instead of a dash in '%s'." -link: https://docs.microsoft.com/en-us/style-guide/numbers -nonword: true -level: error -action: - name: edit - params: - - regex - - "[-–]" - - "to" -tokens: - - '\b(?:AM|PM)\s?[-–]\s?.+(?:AM|PM)\b' diff --git a/.vale/styles/Microsoft/Semicolon.yml b/.vale/styles/Microsoft/Semicolon.yml deleted file mode 100644 index 4d905467dd2..00000000000 --- a/.vale/styles/Microsoft/Semicolon.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "Try to simplify this sentence." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/semicolons -nonword: true -scope: sentence -level: suggestion -tokens: - - ';' diff --git a/.vale/styles/Microsoft/SentenceLength.yml b/.vale/styles/Microsoft/SentenceLength.yml deleted file mode 100644 index f248cf0513b..00000000000 --- a/.vale/styles/Microsoft/SentenceLength.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: occurrence -message: "Try to keep sentences short (< 30 words)." -scope: sentence -level: suggestion -max: 30 -token: \b(\w+)\b - diff --git a/.vale/styles/Microsoft/Spacing.yml b/.vale/styles/Microsoft/Spacing.yml deleted file mode 100644 index bbd10e51df7..00000000000 --- a/.vale/styles/Microsoft/Spacing.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "'%s' should have one space." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods -level: error -nonword: true -tokens: - - '[a-z][.?!] {2,}[A-Z]' - - '[a-z][.?!][A-Z]' diff --git a/.vale/styles/Microsoft/Suspended.yml b/.vale/styles/Microsoft/Suspended.yml deleted file mode 100644 index 7282e9c9cf5..00000000000 --- a/.vale/styles/Microsoft/Suspended.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Don't use '%s' unless space is limited." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens -ignorecase: true -level: warning -tokens: - - '\w+- and \w+-' diff --git a/.vale/styles/Microsoft/Terms.yml b/.vale/styles/Microsoft/Terms.yml deleted file mode 100644 index 65fca10aaa8..00000000000 --- a/.vale/styles/Microsoft/Terms.yml +++ /dev/null @@ -1,42 +0,0 @@ -extends: substitution -message: "Prefer '%s' over '%s'." -# term preference should be based on microsoft style guide, such as -link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter -level: warning -ignorecase: true -action: - name: replace -swap: - "(?:agent|virtual assistant|intelligent personal assistant)": personal digital assistant - "(?:assembler|machine language)": assembly language - "(?:drive C:|drive C>|C: drive)": drive C - "(?:internet bot|web robot)s?": bot(s) - "(?:microsoft cloud|the cloud)": cloud - "(?:mobile|smart) ?phone": phone - "24/7": every day - "audio(?:-| )book": audiobook - "back(?:-| )light": backlight - "chat ?bots?": chatbot(s) - adaptor: adapter - administrate: administer - afterwards: afterward - alphabetic: alphabetical - alphanumerical: alphanumeric - an URL: a URL - anti-aliasing: antialiasing - anti-malware: antimalware - anti-spyware: antispyware - anti-virus: antivirus - appendixes: appendices - artificial intelligence: AI - caap: CaaP - conversation-as-a-platform: conversation as a platform - eb: EB - gb: GB - gbps: Gbps - kb: KB - keypress: keystroke - mb: MB - pb: PB - tb: TB - zb: ZB diff --git a/.vale/styles/Microsoft/URLFormat.yml b/.vale/styles/Microsoft/URLFormat.yml deleted file mode 100644 index 4e24aa59fe0..00000000000 --- a/.vale/styles/Microsoft/URLFormat.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: substitution -message: Use 'of' (not 'for') to describe the relationship of the word URL to a resource. -ignorecase: true -link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/url -level: suggestion -action: - name: replace -swap: - URL for: URL of diff --git a/.vale/styles/Microsoft/Units.yml b/.vale/styles/Microsoft/Units.yml deleted file mode 100644 index f062418ee0d..00000000000 --- a/.vale/styles/Microsoft/Units.yml +++ /dev/null @@ -1,16 +0,0 @@ -extends: existence -message: "Don't spell out the number in '%s'." -link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/units-of-measure-terms -level: error -raw: - - '[a-zA-Z]+\s' -tokens: - - '(?:centi|milli)?meters' - - '(?:kilo)?grams' - - '(?:kilo)?meters' - - '(?:mega)?pixels' - - cm - - inches - - lb - - miles - - pounds diff --git a/.vale/styles/Microsoft/Vocab.yml b/.vale/styles/Microsoft/Vocab.yml deleted file mode 100644 index eebe97b15ee..00000000000 --- a/.vale/styles/Microsoft/Vocab.yml +++ /dev/null @@ -1,25 +0,0 @@ -extends: existence -message: "Verify your use of '%s' with the A-Z word list." -link: 'https://docs.microsoft.com/en-us/style-guide' -level: suggestion -ignorecase: true -tokens: - - above - - accessible - - actionable - - against - - alarm - - alert - - alias - - allows? - - and/or - - as well as - - assure - - author - - avg - - beta - - ensure - - he - - insure - - sample - - she diff --git a/.vale/styles/Microsoft/We.yml b/.vale/styles/Microsoft/We.yml deleted file mode 100644 index 97c901c1bae..00000000000 --- a/.vale/styles/Microsoft/We.yml +++ /dev/null @@ -1,11 +0,0 @@ -extends: existence -message: "Try to avoid using first-person plural like '%s'." -link: https://docs.microsoft.com/en-us/style-guide/grammar/person#avoid-first-person-plural -level: warning -ignorecase: true -tokens: - - we - - we'(?:ve|re) - - ours? - - us - - let's diff --git a/.vale/styles/Microsoft/Wordiness.yml b/.vale/styles/Microsoft/Wordiness.yml deleted file mode 100644 index 8a4fea74833..00000000000 --- a/.vale/styles/Microsoft/Wordiness.yml +++ /dev/null @@ -1,127 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of '%s'." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences -ignorecase: true -level: suggestion -action: - name: replace -swap: - "sufficient number(?: of)?": enough - (?:extract|take away|eliminate): remove - (?:in order to|as a means to): to - (?:inform|let me know): tell - (?:previous|prior) to: before - (?:utilize|make use of): use - a (?:large)? majority of: most - a (?:large)? number of: many - a myriad of: myriad - adversely impact: hurt - all across: across - all of a sudden: suddenly - all of these: these - all of(?! a sudden| these): all - all-time record: record - almost all: most - almost never: seldom - along the lines of: similar to - an adequate number of: enough - an appreciable number of: many - an estimated: about - any and all: all - are in agreement: agree - as a matter of fact: in fact - as a means of: to - as a result of: because of - as of yet: yet - as per: per - at a later date: later - at all times: always - at the present time: now - at this point in time: at this point - based in large part on: based on - based on the fact that: because - basic necessity: necessity - because of the fact that: because - came to a realization: realized - came to an abrupt end: ended abruptly - carry out an evaluation of: evaluate - close down: close - closed down: closed - complete stranger: stranger - completely separate: separate - concerning the matter of: regarding - conduct a review of: review - conduct an investigation: investigate - conduct experiments: experiment - continue on: continue - despite the fact that: although - disappear from sight: disappear - doomed to fail: doomed - drag and drop: drag - drag-and-drop: drag - due to the fact that: because - during the period of: during - during the time that: while - emergency situation: emergency - establish connectivity: connect - except when: unless - excessive number: too many - extend an invitation: invite - fall down: fall - fell down: fell - for the duration of: during - gather together: gather - has the ability to: can - has the capacity to: can - has the opportunity to: could - hold a meeting: meet - if this is not the case: if not - in a careful manner: carefully - in a thoughtful manner: thoughtfully - in a timely manner: timely - in addition: also - in an effort to: to - in between: between - in lieu of: instead of - in many cases: often - in most cases: usually - in order to: to - in some cases: sometimes - in spite of the fact that: although - in spite of: despite - in the (?:very)? near future: soon - in the event that: if - in the neighborhood of: roughly - in the vicinity of: close to - it would appear that: apparently - lift up: lift - made reference to: referred to - make reference to: refer to - mix together: mix - none at all: none - not in a position to: unable - not possible: impossible - of major importance: important - perform an assessment of: assess - pertaining to: about - place an order: order - plays a key role in: is essential to - present time: now - readily apparent: apparent - some of the: some - span across: span - subsequent to: after - successfully complete: complete - take action: act - take into account: consider - the question as to whether: whether - there is no doubt but that: doubtless - this day and age: this age - this is a subject that: this subject - time (?:frame|period): time - under the provisions of: under - until such time as: until - used for fuel purposes: used for fuel - whether or not: whether - with regard to: regarding - with the exception of: except for diff --git a/.vale/styles/Microsoft/meta.json b/.vale/styles/Microsoft/meta.json deleted file mode 100644 index 297719bbbff..00000000000 --- a/.vale/styles/Microsoft/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "feed": "https://github.com/errata-ai/Microsoft/releases.atom", - "vale_version": ">=1.0.0" -} From 8244ff035bc2212bb60cb878530b4ad5647a67b5 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Tue, 26 May 2026 17:17:28 +0200 Subject: [PATCH 04/19] Add GH action --- .github/workflows/vale.yml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/workflows/vale.yml diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000000..c27fef894f4 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,36 @@ +name: Vale Linting + +# Trigger on PRs that change Markdown files +on: + pull_request: + paths: + - 'content/en/docs/**/*.md' + +# Allow reading repo contents and posting PR comments +permissions: + contents: read + pull-requests: write + +jobs: + vale: + # Only run on Mendix repo, not forks, and not on draft PRs + if: github.repository_owner == 'mendix' && github.event.pull_request.draft == false + runs-on: ubuntu-latest + # Cancel old runs when new commits are pushed + concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Run Vale + uses: errata-ai/vale-action@reviewdog + with: + files: '.' # Check all changed files in the PR + version: 3.14.2 + fail_on_error: false + level: error # Only flag errors, not warnings or suggestions + filter_mode: diff_context # Only check changed lines, not entire files + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} From 22c6730e94f09bad654047c6d2f631228894e2f8 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 27 May 2026 12:11:21 +0200 Subject: [PATCH 05/19] Add readmes and setup guide --- .vale/README.md | 31 +++++++++++++++ .vale/SETUP.md | 65 ++++++++++++++++++++++++++++++++ .vale/styles/Mendix/README.md | 71 ++++++++--------------------------- 3 files changed, 112 insertions(+), 55 deletions(-) create mode 100644 .vale/README.md create mode 100644 .vale/SETUP.md diff --git a/.vale/README.md b/.vale/README.md new file mode 100644 index 00000000000..28d0d6783bc --- /dev/null +++ b/.vale/README.md @@ -0,0 +1,31 @@ +# Vale Configuration for Mendix Documentation + +[Vale](https://vale.sh/docs/) lints the documentation with both Microsoft Writing Style Guide rules and custom Mendix rules. + +It applies in the following contexts: + +* **GitHub PRs**: Runs automatically on PRs marked "Ready for review" and posts inline comments on changed lines. Only shows errors (warnings and suggestions are hidden). +* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. + +Need to install Vale? See [SETUP.md](./SETUP.md) for installation and verification steps. + +## File Structure + +``` +.vale.ini # Main configuration +.vale/ + styles/ + Microsoft/ # Synced from vale.sh (gitignored) + Mendix/ # Custom rules (committed to Git) + *.yml # Mendix-specific style rules + README.md # Rule documentation +``` + +See [.vale/styles/Mendix/README.md](styles/Mendix/README.md) for the complete list of custom rules and overrides. + +## Read More + +* [Vale Documentation](https://vale.sh/docs/) +* [Microsoft Style Guide Package](https://github.com/errata-ai/Microsoft) +* [Vale Rule Syntax](https://vale.sh/docs/topics/styles/) +* [Custom Mendix Rules](.vale/styles/Mendix/README.md) diff --git a/.vale/SETUP.md b/.vale/SETUP.md new file mode 100644 index 00000000000..f1d03a956cb --- /dev/null +++ b/.vale/SETUP.md @@ -0,0 +1,65 @@ +# Vale Setup Guide + +Vale is configured but not yet installed. This guide walks you through setup. + +## Why Install Locally? + +- **Immediate feedback** - See violations as you write, not after pushing +- **Faster iteration** - Fix issues before creating a PR +- **More feedback** - See suggestions and warnings locally; the GitHub Action is configured to only show errors + +**Note:** Even without local installation, your PRs will be checked automatically by a GitHub Action: [.github/workflows/vale.yml](../.github/workflows/vale.yml). + +## Installation (Choose One) + +### For macOS + +First, download Homebrew if you don't already have it: https://brew.sh/ + +```bash +brew install vale +``` + +### For Windows + +1. On https://github.com/vale-cli/vale/releases, download the Windows version from Assets +2. Right-click the zip file and select **Extract All** +3. Open PowerShell and run: + + ```powershell + # Create a bin directory for your tools + mkdir $HOME\bin -Force + + # Move vale.exe there (adjust the path if you extracted it elsewhere) + Move-Item $HOME\Downloads\vale_*_Windows_64-bit\vale.exe $HOME\bin\ + + # Add to PATH + $currentPath = [Environment]::GetEnvironmentVariable("Path", "User") + [Environment]::SetEnvironmentVariable("Path", "$currentPath;$HOME\bin", "User") + ``` + +## Post-Installation + +After installing Vale: + +1. **Verify the installation worked:** + + ```bash + vale --version + ``` + +2. **Sync the Microsoft Style Guide rules:** + + ```bash + vale sync + ``` + + This downloads Microsoft's style pack to `.vale/styles/Microsoft/`. + +3. **Install VS Code extension:** + - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) + - Restart VS Code + - Open any `.md` file in `content/en/docs/` + - Violations show as squiggly underlines in the file and appear in the **Problems** tab + +4. **If you have open PRs:** Merge `development` into your branch to get the Vale configuration files. \ No newline at end of file diff --git a/.vale/styles/Mendix/README.md b/.vale/styles/Mendix/README.md index c4abd13805a..6883763b168 100644 --- a/.vale/styles/Mendix/README.md +++ b/.vale/styles/Mendix/README.md @@ -4,45 +4,25 @@ This directory contains custom Vale rules specific to Mendix documentation. ## Current Rules -- **AmericanSpelling.yml**: Enforces American English spelling (colour→color, organise→organize, etc.) -- **Acronyms.yml**: Validates acronym definitions and usage -- **Capitalization.yml**: Enforces proper capitalization for Mendix terms -- **ClickOn.yml**: Prohibits "click on" in favor of "click" -- **CompoundWords.yml**: Enforces proper compound word formatting -- **ConditionalAdverbs.yml**: Flags unnecessary conditional adverbs -- **Dashes.yml**: Enforces en dash usage in number ranges -- **Directions.yml**: Standardizes directional language -- **HeadingPunctuation.yml**: Prohibits end punctuation in headings (except question marks) -- **HeadingTitleCase.yml**: Enforces title case in headings -- **Inclusive.yml**: Flags non-inclusive language -- **LinkText.yml**: Prohibits generic link text like "click here" -- **ListIntroductions.yml**: Enforces en dashes in list item introductions (≤40 chars) -- **ProductNames.yml**: Enforces correct Mendix product names -- **SignIn.yml**: Standardizes "sign in" vs "sign-in" usage - -## Rule Types - -Vale supports several rule types (`extends`): - -- **substitution**: Simple find-and-replace (case-sensitive or insensitive) -- **existence**: Check if patterns exist (for prohibited terms) -- **occurrence**: Limit how often a term appears -- **repetition**: Flag repeated words -- **consistency**: Ensure consistent usage (e.g., "app" vs "application") -- **conditional**: Complex logic (if X then Y must follow) -- **capitalization**: Enforce capitalization patterns -- **readability**: Check reading level -- **spelling**: Custom dictionary - -## Severity Levels - -- `error`: Must fix -- `warning`: Should review -- `suggestion`: Nice to have +* **Acronyms.yml**: Validates acronym definitions and usage +* **AmericanSpelling.yml**: Enforces American English spelling +* **Capitalization.yml**: Enforces proper capitalization for Mendix terms +* **ClickOn.yml**: Prohibits "click on" in favor of "click" +* **CompoundWords.yml**: Enforces proper compound word formatting +* **ConditionalAdverbs.yml**: Flags conditional adverbs that add uncertainty (would, could, should, might, etc.) +* **Dashes.yml**: Removes spaces around em dashes (—) +* **Directions.yml**: Enforces upper/lower instead of top/bottom for directional terms +* **HeadingPunctuation.yml**: Prohibits end punctuation in headings (except question marks) +* **HeadingTitleCase.yml**: Enforces title case in headings +* **Inclusive.yml**: Flags non-inclusive language +* **LinkText.yml**: Prohibits generic link text like "click here" +* **ListIntroductions.yml**: Enforces en dashes in list item introductions (≤40 chars) +* **ProductNames.yml**: Enforces correct Mendix product names +* **SignIn.yml**: Enforces "sign in/out" instead of "log in/out" ## Adding New Rules -Create a new `.yml` file in this directory: +Create a new `.yml` file in this directory, following [Vale's style documentation](https://vale.sh/docs/styles): ```yaml # Mendix/MyRule.yml @@ -54,19 +34,6 @@ swap: 'bad term': 'good term' ``` -## Testing Rules - -```bash -# Test against a specific file -.claude/bin/vale content/en/docs/path/to/file.md - -# Test only Mendix rules -.claude/bin/vale --config=".vale.ini" --filter="\.Mendix\." file.md - -# List all active rules -.claude/bin/vale ls-config -``` - ## Overriding Microsoft Rules In `.vale.ini`: @@ -78,9 +45,3 @@ Microsoft.Contractions = NO # Change severity Microsoft.Wordiness = warning ``` - -## Documentation - -- Vale docs: https://vale.sh/docs/ -- Rule examples: https://vale.sh/docs/topics/styles/ -- Microsoft package: https://github.com/errata-ai/Microsoft From d37d32f18e1b873085ea58cb015ca59683d28440 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 27 May 2026 15:31:07 +0200 Subject: [PATCH 06/19] Update scopes and actions --- .vale.ini | 3 +-- .vale/styles/Mendix/Acronyms.yml | 7 ++++++- .vale/styles/Mendix/Capitalization.yml | 10 ++++++++-- .vale/styles/Mendix/ClickOn.yml | 8 ++++++++ .vale/styles/Mendix/CompoundWords.yml | 8 ++++++++ .vale/styles/Mendix/Dashes.yml | 8 ++++++++ .vale/styles/Mendix/Directions.yml | 8 ++++++++ .vale/styles/Mendix/Inclusive.yml | 8 ++++++++ .vale/styles/Mendix/ListIntroductions.yml | 2 ++ .vale/styles/Mendix/ProductNames.yml | 8 ++++++++ .vale/styles/Mendix/SignIn.yml | 8 ++++++++ 11 files changed, 73 insertions(+), 5 deletions(-) diff --git a/.vale.ini b/.vale.ini index 20556a65626..a5ce80854ff 100644 --- a/.vale.ini +++ b/.vale.ini @@ -13,8 +13,7 @@ Packages = Microsoft # Ignore code blocks BlockIgnores = (?s) *```(?:[\w\{\}]+)?$(.+?)^ *``` # Ignore front matter (YAML blocks at start of file), anchor IDs in headings, and Hugo shortcodes -# Content matched by TokenIgnores is treated as 'raw' scope by Vale -# Rules must use scope: '!raw' to exclude front matter +# Rules can use explicit scope lists (paragraph, heading, list, table, blockquote) to exclude this content TokenIgnores = (\A---\s*\n(.|\n)+?\n---\s*\n), (\{#[^\}]+\}), (\{\{[^\}]+\}\}) # Markdown files use both Microsoft and custom Mendix styles diff --git a/.vale/styles/Mendix/Acronyms.yml b/.vale/styles/Mendix/Acronyms.yml index 444a36841e4..15927b822ff 100644 --- a/.vale/styles/Mendix/Acronyms.yml +++ b/.vale/styles/Mendix/Acronyms.yml @@ -3,7 +3,12 @@ message: "Define '%s' on first use." link: https://docs.microsoft.com/en-us/style-guide/acronyms level: suggestion ignorecase: false -scope: '!raw' +scope: + - paragraph + - heading + - list + - table + - blockquote # Ensures that the existence of 'first' implies the existence of 'second'. # Modified from Microsoft.Acronyms to accept sentence-case definitions # e.g., "personal access token (PAT)" not just "Personal Access Token (PAT)" diff --git a/.vale/styles/Mendix/Capitalization.yml b/.vale/styles/Mendix/Capitalization.yml index 66504396bf9..976e10800e3 100644 --- a/.vale/styles/Mendix/Capitalization.yml +++ b/.vale/styles/Mendix/Capitalization.yml @@ -5,7 +5,14 @@ extends: substitution message: "Use '%s' (capitalized)" level: error ignorecase: true -scope: '!raw' +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: agents kit: Agents Kit boolean: Boolean @@ -17,7 +24,6 @@ swap: postgres: Postgres postgresql: PostgreSQL scrum: Scrum - sprint: Sprint sql: SQL 'atlas ui': 'Atlas UI' 'build server': 'Build Server' diff --git a/.vale/styles/Mendix/ClickOn.yml b/.vale/styles/Mendix/ClickOn.yml index a32f3808d79..5eebcfa703a 100644 --- a/.vale/styles/Mendix/ClickOn.yml +++ b/.vale/styles/Mendix/ClickOn.yml @@ -4,6 +4,14 @@ extends: substitution message: "Use '%s' instead of '%s'" level: error ignorecase: true +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: 'click on': 'click' 'clicking on': 'clicking' diff --git a/.vale/styles/Mendix/CompoundWords.yml b/.vale/styles/Mendix/CompoundWords.yml index 78abd4bb608..4b31c31f7e2 100644 --- a/.vale/styles/Mendix/CompoundWords.yml +++ b/.vale/styles/Mendix/CompoundWords.yml @@ -5,6 +5,14 @@ extends: substitution message: "Use '%s' instead of '%s'" level: error ignorecase: true +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: 'data-set': 'dataset' 'data set': 'dataset' diff --git a/.vale/styles/Mendix/Dashes.yml b/.vale/styles/Mendix/Dashes.yml index a8239f9793d..d9be3286fd0 100644 --- a/.vale/styles/Mendix/Dashes.yml +++ b/.vale/styles/Mendix/Dashes.yml @@ -5,6 +5,14 @@ link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/em ignorecase: false nonword: true level: error +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: # Em dashes (—) should not have spaces ' — ': '—' diff --git a/.vale/styles/Mendix/Directions.yml b/.vale/styles/Mendix/Directions.yml index 66409cfedbe..276c31bca87 100644 --- a/.vale/styles/Mendix/Directions.yml +++ b/.vale/styles/Mendix/Directions.yml @@ -4,6 +4,14 @@ extends: substitution message: "Use '%s' instead of '%s'" level: error ignorecase: true +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: 'top left': 'upper left' 'top-left': 'upper-left' diff --git a/.vale/styles/Mendix/Inclusive.yml b/.vale/styles/Mendix/Inclusive.yml index 4be20a375f3..a5e724f80c1 100644 --- a/.vale/styles/Mendix/Inclusive.yml +++ b/.vale/styles/Mendix/Inclusive.yml @@ -4,6 +4,14 @@ extends: substitution message: "Use '%s' instead of '%s'" level: error ignorecase: true +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: blacklist: blocklist whitelist: allowlist diff --git a/.vale/styles/Mendix/ListIntroductions.yml b/.vale/styles/Mendix/ListIntroductions.yml index f79f07eec0f..e363465e42e 100644 --- a/.vale/styles/Mendix/ListIntroductions.yml +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -5,6 +5,8 @@ ignorecase: false nonword: true level: error scope: list +action: + name: replace swap: # Match up to 40 chars + word/slash/digit + space + em dash + space '^.{0,40}([a-zA-Z0-9/]) — ': '$1 – ' diff --git a/.vale/styles/Mendix/ProductNames.yml b/.vale/styles/Mendix/ProductNames.yml index 77c327f3813..4d9dc79a646 100644 --- a/.vale/styles/Mendix/ProductNames.yml +++ b/.vale/styles/Mendix/ProductNames.yml @@ -4,6 +4,14 @@ extends: substitution message: "Use '%s' instead of '%s'" level: error ignorecase: false +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: # Main product deprecated names 'Mendix for Private Cloud': 'Mendix on Kubernetes' diff --git a/.vale/styles/Mendix/SignIn.yml b/.vale/styles/Mendix/SignIn.yml index a83c8b16c26..4b874d1c9bb 100644 --- a/.vale/styles/Mendix/SignIn.yml +++ b/.vale/styles/Mendix/SignIn.yml @@ -4,6 +4,14 @@ extends: substitution message: "Use '%s' instead of '%s' (unless referring to UI button text)" level: warning ignorecase: true +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace swap: 'log in': 'sign in' 'log out': 'sign out' From da795e2f6b24c9776a196a8677f0f9ac5c87183d Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 27 May 2026 15:50:05 +0200 Subject: [PATCH 07/19] Update foreign.yml quick fix --- .vale/README.md | 2 +- .vale/styles/Mendix/Foreign.yml | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 .vale/styles/Mendix/Foreign.yml diff --git a/.vale/README.md b/.vale/README.md index 28d0d6783bc..559a86820a7 100644 --- a/.vale/README.md +++ b/.vale/README.md @@ -5,7 +5,7 @@ It applies in the following contexts: * **GitHub PRs**: Runs automatically on PRs marked "Ready for review" and posts inline comments on changed lines. Only shows errors (warnings and suggestions are hidden). -* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. +* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. Many Vale rules support automatic fixes—click the lightbulb icon next to flagged text in the Problems tab or hover over an underlined issue and click **Quick Fix**. Need to install Vale? See [SETUP.md](./SETUP.md) for installation and verification steps. diff --git a/.vale/styles/Mendix/Foreign.yml b/.vale/styles/Mendix/Foreign.yml new file mode 100644 index 00000000000..82154ff71b2 --- /dev/null +++ b/.vale/styles/Mendix/Foreign.yml @@ -0,0 +1,15 @@ +# Override Microsoft.Foreign for better i.e./e.g. replacements +# The Microsoft rule removes spacing incorrectly when applying quick fixes +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: false +swap: + 'i\.e\., ': 'that is, ' + 'i\.e\. ': 'that is, ' + 'e\.g\., ': 'for example, ' + 'e\.g\. ': 'for example, ' + '\(i\.e\., ': '(that is, ' + '\(i\.e\. ': '(that is, ' + '\(e\.g\., ': '(for example, ' + '\(e\.g\. ': '(for example, ' From cf21716e586308b97e67da34d70ef6d27ddb290d Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 27 May 2026 15:50:21 +0200 Subject: [PATCH 08/19] Add capitalization terms --- .vale/styles/Mendix/Capitalization.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.vale/styles/Mendix/Capitalization.yml b/.vale/styles/Mendix/Capitalization.yml index 976e10800e3..771889fb779 100644 --- a/.vale/styles/Mendix/Capitalization.yml +++ b/.vale/styles/Mendix/Capitalization.yml @@ -17,7 +17,10 @@ swap: agents kit: Agents Kit boolean: Boolean git: Git + idp: IdP + ios: iOS java: Java + macos: macOS marketplace: Marketplace mendix: Mendix 'n/a': 'N/A' @@ -25,6 +28,7 @@ swap: postgresql: PostgreSQL scrum: Scrum sql: SQL + 'agile scrum': 'Agile Scrum' 'atlas ui': 'Atlas UI' 'build server': 'Build Server' 'business engineer': 'Business Engineer' From 721311be1de8879a6c688607a4a24264d1602943 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 27 May 2026 15:50:39 +0200 Subject: [PATCH 09/19] Update vale.ini for foreign.yml --- .vale.ini | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.vale.ini b/.vale.ini index a5ce80854ff..f562482629c 100644 --- a/.vale.ini +++ b/.vale.ini @@ -42,6 +42,11 @@ Microsoft.Contractions = NO # Mendix.ListIntroductions enforces en dashes (not em dashes) for list item introductions Microsoft.Dashes = NO +# Foreign +# Microsoft's i.e./e.g. replacements remove spacing incorrectly when applied as quick fixes +# Replacement: Mendix.Foreign provides correct spacing and punctuation in replacements +Microsoft.Foreign = NO + # General URL # Microsoft prefers "address" over "URL"; Mendix does not Microsoft.GeneralURL = NO From 0cb989f070e4511a5f7ae06144396e67c2eebbf1 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Thu, 28 May 2026 10:12:18 +0200 Subject: [PATCH 10/19] Troubleshoot list intros --- .vale/styles/Mendix/ListIntroductions.yml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/.vale/styles/Mendix/ListIntroductions.yml b/.vale/styles/Mendix/ListIntroductions.yml index e363465e42e..db873d89809 100644 --- a/.vale/styles/Mendix/ListIntroductions.yml +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -8,11 +8,8 @@ scope: list action: name: replace swap: - # Match up to 40 chars + word/slash/digit + space + em dash + space - '^.{0,40}([a-zA-Z0-9/]) — ': '$1 – ' - # Match up to 40 chars + word/slash/digit + space + em dash no trailing space - '^.{0,40}([a-zA-Z0-9/]) —': '$1 – ' - # Match up to 40 chars + word/slash/digit + em dash + space no leading space - '^.{0,40}([a-zA-Z0-9/])— ': '$1 – ' - # Match up to 40 chars + word/slash/digit + em dash no spaces - '^.{0,40}([a-zA-Z0-9/])—': '$1 – ' + # Match up to 40 chars (excluding em dashes) from start of line, then replace first em dash with en dash + # Limit to first ~40 chars to avoid matching em dashes in the middle of list text + '^([^—]{0,40}) — ': '$1 – ' # em dash with spaces on both sides + '^([^—]{0,40}) —': '$1 – ' # em dash with space before, no space after + '^([^—]{0,40})— ': '$1 – ' # em dash with no space before, space after \ No newline at end of file From 2417392d5aa370e38a6f9d693a0b7960464e4853 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Thu, 28 May 2026 10:12:47 +0200 Subject: [PATCH 11/19] Revert vale-off in claude.md --- CLAUDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3aff429caa7..f8f16033de0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,5 @@ # Mendix Documentation Repository - **Your role**: Edit and review Markdown documentation files under `content/en/docs/` following the style guidance and project-specific conventions below. From 1f0f75e31be94cc5e08a7e5bfe5cc64cf4ee7e3a Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Thu, 28 May 2026 10:15:34 +0200 Subject: [PATCH 12/19] Update readme and setup guide --- .vale/README.md | 4 ++-- .vale/SETUP.md | 9 +++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.vale/README.md b/.vale/README.md index 559a86820a7..ccaf2843fdb 100644 --- a/.vale/README.md +++ b/.vale/README.md @@ -5,9 +5,9 @@ It applies in the following contexts: * **GitHub PRs**: Runs automatically on PRs marked "Ready for review" and posts inline comments on changed lines. Only shows errors (warnings and suggestions are hidden). -* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. Many Vale rules support automatic fixes—click the lightbulb icon next to flagged text in the Problems tab or hover over an underlined issue and click **Quick Fix**. +* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. -Need to install Vale? See [SETUP.md](./SETUP.md) for installation and verification steps. +Need to install Vale? See [SETUP.md](./SETUP.md) for installation steps. ## File Structure diff --git a/.vale/SETUP.md b/.vale/SETUP.md index f1d03a956cb..a57583eb00b 100644 --- a/.vale/SETUP.md +++ b/.vale/SETUP.md @@ -57,9 +57,10 @@ After installing Vale: This downloads Microsoft's style pack to `.vale/styles/Microsoft/`. 3. **Install VS Code extension:** - - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) - - Restart VS Code - - Open any `.md` file in `content/en/docs/` - - Violations show as squiggly underlines in the file and appear in the **Problems** tab + - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). + - Restart VS Code. + - Open any `.md` file in `content/en/docs/`. + - Violations show as squiggly underlines in the file and appear in the **Problems** tab. Many Vale rules support automatic fixes—click the lightbulb icon next to flagged text in the Problems tab or hover over an underlined issue and click **Quick Fix**. + - Save changes to rerun the linter. 4. **If you have open PRs:** Merge `development` into your branch to get the Vale configuration files. \ No newline at end of file From 605939d46ece7c27e7dbda4dc0c89cc7aee87bcf Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Thu, 28 May 2026 16:54:45 +0200 Subject: [PATCH 13/19] Update based on feedback --- .vale.ini | 8 ++++++++ .vale/SETUP.md | 5 ++++- .vale/styles/Mendix/Acronyms.yml | 1 + 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index f562482629c..6813e3cb2a8 100644 --- a/.vale.ini +++ b/.vale.ini @@ -66,6 +66,10 @@ Microsoft.Headings = NO # Replacement: Mendix.HeadingPunctuation prohibits periods, exclamation marks, and colons but allows question marks Microsoft.HeadingPunctuation = NO +# Passive +# Too many that don't need changes +Microsoft.Passive = NO + # Spacing # Technical content like **StationConnector.Administrator** triggers false positives Microsoft.Spacing = NO @@ -74,6 +78,10 @@ Microsoft.Spacing = NO # Too far off from Mendix terminology guidance Microsoft.Terms = NO +# Vocab +# Too far off from Mendix terminology guidance +Microsoft.Vocab = NO + # ============================================================================ # Path-Specific Overrides # ============================================================================ diff --git a/.vale/SETUP.md b/.vale/SETUP.md index a57583eb00b..2088463696c 100644 --- a/.vale/SETUP.md +++ b/.vale/SETUP.md @@ -50,6 +50,8 @@ After installing Vale: 2. **Sync the Microsoft Style Guide rules:** + Switch to the docs directory (`cd docs`), then run: + ```bash vale sync ``` @@ -60,7 +62,8 @@ After installing Vale: - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). - Restart VS Code. - Open any `.md` file in `content/en/docs/`. - - Violations show as squiggly underlines in the file and appear in the **Problems** tab. Many Vale rules support automatic fixes—click the lightbulb icon next to flagged text in the Problems tab or hover over an underlined issue and click **Quick Fix**. + - Violations show as squiggly underlines in the file and appear in the **Problems** tab in the bottom pane. + - Many Vale rules support automatic fixes—hover over an underlined issue and click **Quick Fix** or click the lightbulb icon next to flagged text in the **Problems** tab. - Save changes to rerun the linter. 4. **If you have open PRs:** Merge `development` into your branch to get the Vale configuration files. \ No newline at end of file diff --git a/.vale/styles/Mendix/Acronyms.yml b/.vale/styles/Mendix/Acronyms.yml index 15927b822ff..a38e38c55c2 100644 --- a/.vale/styles/Mendix/Acronyms.yml +++ b/.vale/styles/Mendix/Acronyms.yml @@ -51,6 +51,7 @@ exceptions: - POST - RAM - REPL + - REST - RSA - SCM - SCSS From 73f07a7bf981d67818ba2da3e9c4a4c3e4037abe Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 12:07:34 +0200 Subject: [PATCH 14/19] Clarify readme --- .vale/README.md | 35 +++++++++++++++++---- .vale/styles/Mendix/{README.md => RULES.md} | 0 2 files changed, 29 insertions(+), 6 deletions(-) rename .vale/styles/Mendix/{README.md => RULES.md} (100%) diff --git a/.vale/README.md b/.vale/README.md index ccaf2843fdb..d2d028caa67 100644 --- a/.vale/README.md +++ b/.vale/README.md @@ -1,13 +1,13 @@ # Vale Configuration for Mendix Documentation -[Vale](https://vale.sh/docs/) lints the documentation with both Microsoft Writing Style Guide rules and custom Mendix rules. +[Vale](https://vale.sh/docs/) lints the documentation with both Microsoft Writing Style Guide rules and custom Mendix rules to catch style violations, grammar issues, and terminology inconsistencies. It matches text against patterns and rules defined in the .vale/styles YAML files, providing deterministic feedback based on these configurable rules. It applies in the following contexts: * **GitHub PRs**: Runs automatically on PRs marked "Ready for review" and posts inline comments on changed lines. Only shows errors (warnings and suggestions are hidden). -* **Local**: Install Vale for immediate feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. +* **Local**: Install Vale for immediate, offline feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. -Need to install Vale? See [SETUP.md](./SETUP.md) for installation steps. +Need to install Vale? See [SETUP.md](/.vale/SETUP.md) for installation steps. ## File Structure @@ -18,14 +18,37 @@ Need to install Vale? See [SETUP.md](./SETUP.md) for installation steps. Microsoft/ # Synced from vale.sh (gitignored) Mendix/ # Custom rules (committed to Git) *.yml # Mendix-specific style rules - README.md # Rule documentation + RULES.md # Complete list of Mendix custom rules and overrides + README.md # Rule documentation ``` -See [.vale/styles/Mendix/README.md](styles/Mendix/README.md) for the complete list of custom rules and overrides. +## What the Rules Check + +Vale is configured to enforce both general writing best practices and Mendix-specific standards: + +* **Microsoft Style Guide rules**: Grammar, punctuation, readability, inclusive language, and general technical writing conventions +* **Mendix custom rules**: Product terminology, capitalization standards, forbidden phrases, link formatting, and documentation-specific patterns + +Rules are categorized by severity: +* **Suggestions**: Recommendations that improve clarity but aren't mandatory +* **Warnings**: Style violations that should be fixed before merging +* **Errors**: Critical issues that must be resolved + +Each rule uses an `action` type to define what it checks: + +* `suggest`: Offers alternative phrasing or improvements +* `replace`: Identifies text to replace with specific alternatives +* `remove`: Flags text to delete (for example, redundant words) +* `existence`: Detects the presence of forbidden patterns or phrases +* `substitution`: Finds patterns and suggests substitutions +* `occurrence`: Checks for repeated or missing patterns +* `conditional`: Applies rules based on context + +For a complete list of custom Mendix rules and overrides, see [Custom Mendix Rules](/.vale/styles/Mendix/RULES.md). ## Read More * [Vale Documentation](https://vale.sh/docs/) * [Microsoft Style Guide Package](https://github.com/errata-ai/Microsoft) * [Vale Rule Syntax](https://vale.sh/docs/topics/styles/) -* [Custom Mendix Rules](.vale/styles/Mendix/README.md) +* [Custom Mendix Rules](/.vale/styles/Mendix/RULES.md) diff --git a/.vale/styles/Mendix/README.md b/.vale/styles/Mendix/RULES.md similarity index 100% rename from .vale/styles/Mendix/README.md rename to .vale/styles/Mendix/RULES.md From c875d636b9c7ceb786aab41a7b5d42cc1149dee6 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 12:32:48 +0200 Subject: [PATCH 15/19] Update Action --- .github/workflows/vale.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index c27fef894f4..d649fa1f1b8 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -25,12 +25,11 @@ jobs: uses: actions/checkout@v4 - name: Run Vale - uses: errata-ai/vale-action@reviewdog + uses: vale-cli/vale-action@v2 with: files: '.' # Check all changed files in the PR version: 3.14.2 fail_on_error: false + reporter: github-pr-review level: error # Only flag errors, not warnings or suggestions - filter_mode: diff_context # Only check changed lines, not entire files - env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + filter_mode: diff_context # Only check around changed lines, not entire files From 15a51e00710d3ffe747298f122bbbd0c18ea6305 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 14:24:53 +0200 Subject: [PATCH 16/19] Fix min alert level syntax --- .github/workflows/vale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index d649fa1f1b8..7a493834295 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -31,5 +31,5 @@ jobs: version: 3.14.2 fail_on_error: false reporter: github-pr-review - level: error # Only flag errors, not warnings or suggestions + vale_flags: '--minAlertLevel=error' # Only flag errors, not warnings or suggestions filter_mode: diff_context # Only check around changed lines, not entire files From 66fdb290df0fa73119152977f6f1f77995646c3b Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 14:25:01 +0200 Subject: [PATCH 17/19] Add known issue --- .vale/styles/Mendix/ListIntroductions.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/styles/Mendix/ListIntroductions.yml b/.vale/styles/Mendix/ListIntroductions.yml index db873d89809..01c5244658b 100644 --- a/.vale/styles/Mendix/ListIntroductions.yml +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -1,4 +1,5 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Lists) +# Known issue: Only matches plaintext list intros extends: substitution message: "Set off list item introductions with an en dash (–), not an em dash (—)." ignorecase: false From 622b6c1525cdb3ca3ba6f96a494b9615ca91a278 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 14:39:58 +0200 Subject: [PATCH 18/19] Add link fields --- .vale/styles/Mendix/Acronyms.yml | 2 +- .vale/styles/Mendix/Capitalization.yml | 1 + .vale/styles/Mendix/ClickOn.yml | 1 + .vale/styles/Mendix/ConditionalAdverbs.yml | 1 + .vale/styles/Mendix/Dashes.yml | 2 +- .vale/styles/Mendix/Directions.yml | 1 + .vale/styles/Mendix/Foreign.yml | 1 + .vale/styles/Mendix/HeadingTitleCase.yml | 1 + .vale/styles/Mendix/LinkText.yml | 2 +- .vale/styles/Mendix/ListIntroductions.yml | 1 + .vale/styles/Mendix/ProductNames.yml | 1 + .vale/styles/Mendix/SignIn.yml | 1 + .../style-guide/grammar-formatting.md | 14 +++++++------- .../style-guide/terminology.md | 6 +++--- 14 files changed, 22 insertions(+), 13 deletions(-) diff --git a/.vale/styles/Mendix/Acronyms.yml b/.vale/styles/Mendix/Acronyms.yml index a38e38c55c2..2e354293e87 100644 --- a/.vale/styles/Mendix/Acronyms.yml +++ b/.vale/styles/Mendix/Acronyms.yml @@ -1,6 +1,6 @@ extends: conditional message: "Define '%s' on first use." -link: https://docs.microsoft.com/en-us/style-guide/acronyms +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#acronyms-and-initialisms level: suggestion ignorecase: false scope: diff --git a/.vale/styles/Mendix/Capitalization.yml b/.vale/styles/Mendix/Capitalization.yml index 771889fb779..9e9f545aec8 100644 --- a/.vale/styles/Mendix/Capitalization.yml +++ b/.vale/styles/Mendix/Capitalization.yml @@ -3,6 +3,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md extends: substitution message: "Use '%s' (capitalized)" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide/ level: error ignorecase: true scope: diff --git a/.vale/styles/Mendix/ClickOn.yml b/.vale/styles/Mendix/ClickOn.yml index 5eebcfa703a..88a706d6f99 100644 --- a/.vale/styles/Mendix/ClickOn.yml +++ b/.vale/styles/Mendix/ClickOn.yml @@ -2,6 +2,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (click) extends: substitution message: "Use '%s' instead of '%s'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#click level: error ignorecase: true scope: diff --git a/.vale/styles/Mendix/ConditionalAdverbs.yml b/.vale/styles/Mendix/ConditionalAdverbs.yml index 18f2b3dea57..30f787c6e21 100644 --- a/.vale/styles/Mendix/ConditionalAdverbs.yml +++ b/.vale/styles/Mendix/ConditionalAdverbs.yml @@ -3,6 +3,7 @@ # "These words add uncertainty and cloud the meaning of sentences." extends: existence message: "Avoid '%s'. These words add uncertainty to technical writing." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#conditional-adverbs level: warning ignorecase: true tokens: diff --git a/.vale/styles/Mendix/Dashes.yml b/.vale/styles/Mendix/Dashes.yml index d9be3286fd0..0bacbbd2405 100644 --- a/.vale/styles/Mendix/Dashes.yml +++ b/.vale/styles/Mendix/Dashes.yml @@ -1,7 +1,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Dashes) extends: substitution message: "Remove spaces around em dashes (—)." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#em-dash ignorecase: false nonword: true level: error diff --git a/.vale/styles/Mendix/Directions.yml b/.vale/styles/Mendix/Directions.yml index 276c31bca87..070e5707004 100644 --- a/.vale/styles/Mendix/Directions.yml +++ b/.vale/styles/Mendix/Directions.yml @@ -2,6 +2,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (lower-left/lower-right) extends: substitution message: "Use '%s' instead of '%s'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#upperlowercase level: error ignorecase: true scope: diff --git a/.vale/styles/Mendix/Foreign.yml b/.vale/styles/Mendix/Foreign.yml index 82154ff71b2..946393fed06 100644 --- a/.vale/styles/Mendix/Foreign.yml +++ b/.vale/styles/Mendix/Foreign.yml @@ -2,6 +2,7 @@ # The Microsoft rule removes spacing incorrectly when applying quick fixes extends: substitution message: "Use '%s' instead of '%s'." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#latin-abbreviations level: error ignorecase: false swap: diff --git a/.vale/styles/Mendix/HeadingTitleCase.yml b/.vale/styles/Mendix/HeadingTitleCase.yml index 470c2d622f4..abcfeeaa7eb 100644 --- a/.vale/styles/Mendix/HeadingTitleCase.yml +++ b/.vale/styles/Mendix/HeadingTitleCase.yml @@ -1,6 +1,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md (Headings and Titles) extends: capitalization message: "Use title case capitalization for '%s'." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#capitalization level: warning scope: heading match: $title diff --git a/.vale/styles/Mendix/LinkText.yml b/.vale/styles/Mendix/LinkText.yml index 72f5876629c..1fbcdb86898 100644 --- a/.vale/styles/Mendix/LinkText.yml +++ b/.vale/styles/Mendix/LinkText.yml @@ -3,7 +3,7 @@ # Reference: CLAUDE.md (Line 85: "Use descriptive link text such as the page title, not 'click here'") extends: existence message: "Use descriptive link text instead of '%s'." -link: https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#hyperlinks level: error ignorecase: true scope: raw diff --git a/.vale/styles/Mendix/ListIntroductions.yml b/.vale/styles/Mendix/ListIntroductions.yml index 01c5244658b..f2d9a5627c3 100644 --- a/.vale/styles/Mendix/ListIntroductions.yml +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -2,6 +2,7 @@ # Known issue: Only matches plaintext list intros extends: substitution message: "Set off list item introductions with an en dash (–), not an em dash (—)." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#en-dash ignorecase: false nonword: true level: error diff --git a/.vale/styles/Mendix/ProductNames.yml b/.vale/styles/Mendix/ProductNames.yml index 4d9dc79a646..7599d77ab38 100644 --- a/.vale/styles/Mendix/ProductNames.yml +++ b/.vale/styles/Mendix/ProductNames.yml @@ -2,6 +2,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md extends: substitution message: "Use '%s' instead of '%s'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide/ level: error ignorecase: false scope: diff --git a/.vale/styles/Mendix/SignIn.yml b/.vale/styles/Mendix/SignIn.yml index 4b874d1c9bb..6b8bf633f86 100644 --- a/.vale/styles/Mendix/SignIn.yml +++ b/.vale/styles/Mendix/SignIn.yml @@ -2,6 +2,7 @@ # Reference: content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md (sign in/sign out) extends: substitution message: "Use '%s' instead of '%s' (unless referring to UI button text)" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#sign-insign-out level: warning ignorecase: true scope: diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md index 135af84998c..7b3d81e0896 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md @@ -6,7 +6,7 @@ description: "Guidelines on grammar, formatting, capitalization, punctuation, li --- -## Acronyms and Initialisms +## Acronyms and Initialisms {#acronyms-and-initialisms} Define technical or obscure acronyms and initialisms. Write them out fully the first time they are used in a document. @@ -86,7 +86,7 @@ When referencing punctuation or code in a sentence, state its name, put it in pa Keep the diversity of users in mind and avoid using colloquial language. -## Conditional Adverbs +## Conditional Adverbs {#conditional-adverbs} Avoid the following conditional adverbs in technical writing: @@ -157,7 +157,7 @@ When cross-referencing a section of another document, add the link to the sectio > For details, see the `[Section Name](/path/to/page/#anchor-id)` section in *Document Title*. -### Hyperlinks +### Hyperlinks {#hyperlinks} For static links to external websites, use the site or page name as the link text instead of the full URL, unless emphasizing the URL format matters. @@ -180,7 +180,7 @@ Use an en dash with spaces around it to set off introductory text in list items. > * **Decline** – Click this button to reject the request. You can also add a reason. After you decline the request, the submitter will receive a notification. > * **Download** – Click this button to download the MPK file of the component. -### Em Dash +### Em Dash {#em-dash} Use an em dash (`—`) to set off a parenthetical phrase with more emphasis than parentheses provide. Do not add spaces around an em dash. @@ -292,9 +292,9 @@ Bold folder names. > In the **config** folder -## Headings and Titles +## Headings and Titles {#headings-and-titles} -### Capitalization +### Capitalization {#capitalization} Use title case for titles and headings: capitalize all words except articles, short prepositions, and conjunctions. Capitalize prepositions in phrasal verbs (for example, "Set Up"). @@ -366,7 +366,7 @@ Capitalize languages. This makes languages consistent with [File Formats](#file- > HTML, XML, XSC, WSDL -## Latin Abbreviations +## Latin Abbreviations {#latin-abbreviations} Do not use "e.g." Use "For example,…" instead. diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md index ddb26ee8523..e91bef2e8f0 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md @@ -125,7 +125,7 @@ Use the verbs "select" and "clear." Write as two words (following the *Microsoft Style Guide*). -## click +## click {#click} Use "click" and not "click on." @@ -455,7 +455,7 @@ Write as one word, not with a hyphen. Capitalize in all instances. We also capitalize "Agile" and "Sprint." -## sign in/sign out +## sign in/sign out {#sign-insign-out} When referring to an action which is taking place, use "sign in" and "sign out" instead of "log in," "login," "log out," "log off," etc. @@ -503,7 +503,7 @@ Can use as a verb. > Click this to toggle the protection level for the content. -## upper left/upper right +## upper left/upper right {#upperlowercase} When used as an adjective, include a hyphen between the words. From 18769d51dbc7a81e391c8009ba842ce1d38b994b Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 14:51:45 +0200 Subject: [PATCH 19/19] Add troubleshooting instruction --- .vale/SETUP.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/.vale/SETUP.md b/.vale/SETUP.md index 2088463696c..7898abb2f4d 100644 --- a/.vale/SETUP.md +++ b/.vale/SETUP.md @@ -4,9 +4,9 @@ Vale is configured but not yet installed. This guide walks you through setup. ## Why Install Locally? -- **Immediate feedback** - See violations as you write, not after pushing -- **Faster iteration** - Fix issues before creating a PR -- **More feedback** - See suggestions and warnings locally; the GitHub Action is configured to only show errors +* **Immediate feedback** - See violations as you write, not after pushing +* **Faster iteration** - Fix issues before creating a PR +* **More feedback** - See suggestions and warnings locally; the GitHub Action is configured to only show errors **Note:** Even without local installation, your PRs will be checked automatically by a GitHub Action: [.github/workflows/vale.yml](../.github/workflows/vale.yml). @@ -14,11 +14,12 @@ Vale is configured but not yet installed. This guide walks you through setup. ### For macOS -First, download Homebrew if you don't already have it: https://brew.sh/ - -```bash -brew install vale -``` +1. Download [Homebrew](https://brew.sh/) if you don't already have it. +2. In your terminal, run the following command: + + ```bash + brew install vale + ``` ### For Windows @@ -58,6 +59,8 @@ After installing Vale: This downloads Microsoft's style pack to `.vale/styles/Microsoft/`. + If you get a `Runtime error: No sources provided` error, verify that there is a `.vale.ini` file in the root of the docs repository (and that you are also in the root of the docs repository). + 3. **Install VS Code extension:** - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). - Restart VS Code.