From aa69dd6717bd93e6ff03c04a448ee399f4f7f924 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 13:43:39 +0200 Subject: [PATCH 1/2] Add vale --- .github/workflows/vale.yml | 35 ++++++++ .vale.ini | 98 ++++++++++++++++++++++ .vale/README.md | 54 ++++++++++++ .vale/SETUP.md | 69 +++++++++++++++ .vale/styles/Mendix/Acronyms.yml | 73 ++++++++++++++++ .vale/styles/Mendix/AmericanSpelling.yml | 47 +++++++++++ .vale/styles/Mendix/Capitalization.yml | 42 ++++++++++ .vale/styles/Mendix/ClickOn.yml | 19 +++++ .vale/styles/Mendix/CompoundWords.yml | 21 +++++ .vale/styles/Mendix/ConditionalAdverbs.yml | 15 ++++ .vale/styles/Mendix/Dashes.yml | 20 +++++ .vale/styles/Mendix/Directions.yml | 23 +++++ .vale/styles/Mendix/Foreign.yml | 15 ++++ .vale/styles/Mendix/HeadingPunctuation.yml | 13 +++ .vale/styles/Mendix/HeadingTitleCase.yml | 14 ++++ .vale/styles/Mendix/Inclusive.yml | 22 +++++ .vale/styles/Mendix/LinkText.yml | 11 +++ .vale/styles/Mendix/ListIntroductions.yml | 15 ++++ .vale/styles/Mendix/ProductNames.yml | 32 +++++++ .vale/styles/Mendix/RULES.md | 47 +++++++++++ .vale/styles/Mendix/SignIn.yml | 19 +++++ 21 files changed, 704 insertions(+) create mode 100644 .github/workflows/vale.yml create mode 100644 .vale.ini create mode 100644 .vale/README.md create mode 100644 .vale/SETUP.md 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/Foreign.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/RULES.md create mode 100644 .vale/styles/Mendix/SignIn.yml diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000000..cdc6713db4c --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,35 @@ +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.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: 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 around changed lines, not entire files diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000..6813e3cb2a8 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,98 @@ +# 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 +# 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 +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 + +# 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 + +# 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 + +# Passive +# Too many that don't need changes +Microsoft.Passive = NO + +# Spacing +# Technical content like **StationConnector.Administrator** triggers false positives +Microsoft.Spacing = NO + +# Terms +# Too far off from Mendix terminology guidance +Microsoft.Terms = NO + +# Vocab +# Too far off from Mendix terminology guidance +Microsoft.Vocab = 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/README.md b/.vale/README.md new file mode 100644 index 00000000000..d2d028caa67 --- /dev/null +++ b/.vale/README.md @@ -0,0 +1,54 @@ +# Vale Configuration for Mendix Documentation + +[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, offline feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors. + +Need to install Vale? See [SETUP.md](/.vale/SETUP.md) for installation 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 + RULES.md # Complete list of Mendix custom rules and overrides + README.md # Rule documentation +``` + +## 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/RULES.md) diff --git a/.vale/SETUP.md b/.vale/SETUP.md new file mode 100644 index 00000000000..2088463696c --- /dev/null +++ b/.vale/SETUP.md @@ -0,0 +1,69 @@ +# 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:** + + Switch to the docs directory (`cd docs`), then run: + + ```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 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 new file mode 100644 index 00000000000..a38e38c55c2 --- /dev/null +++ b/.vale/styles/Mendix/Acronyms.yml @@ -0,0 +1,73 @@ +extends: conditional +message: "Define '%s' on first use." +link: https://docs.microsoft.com/en-us/style-guide/acronyms +level: suggestion +ignorecase: false +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)" +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 + - REST + - 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..771889fb779 --- /dev/null +++ b/.vale/styles/Mendix/Capitalization.yml @@ -0,0 +1,42 @@ +# 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: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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' + postgres: Postgres + postgresql: PostgreSQL + scrum: Scrum + sql: SQL + 'agile scrum': 'Agile Scrum' + '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..5eebcfa703a --- /dev/null +++ b/.vale/styles/Mendix/ClickOn.yml @@ -0,0 +1,19 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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..4b31c31f7e2 --- /dev/null +++ b/.vale/styles/Mendix/CompoundWords.yml @@ -0,0 +1,21 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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..d9be3286fd0 --- /dev/null +++ b/.vale/styles/Mendix/Dashes.yml @@ -0,0 +1,20 @@ +# 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 +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 new file mode 100644 index 00000000000..276c31bca87 --- /dev/null +++ b/.vale/styles/Mendix/Directions.yml @@ -0,0 +1,23 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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/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, ' 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..a5e724f80c1 --- /dev/null +++ b/.vale/styles/Mendix/Inclusive.yml @@ -0,0 +1,22 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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..db873d89809 --- /dev/null +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -0,0 +1,15 @@ +# 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 +action: + name: replace +swap: + # 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 diff --git a/.vale/styles/Mendix/ProductNames.yml b/.vale/styles/Mendix/ProductNames.yml new file mode 100644 index 00000000000..4d9dc79a646 --- /dev/null +++ b/.vale/styles/Mendix/ProductNames.yml @@ -0,0 +1,32 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +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/RULES.md b/.vale/styles/Mendix/RULES.md new file mode 100644 index 00000000000..6883763b168 --- /dev/null +++ b/.vale/styles/Mendix/RULES.md @@ -0,0 +1,47 @@ +# Mendix Custom Vale Rules + +This directory contains custom Vale rules specific to Mendix documentation. + +## Current Rules + +* **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, following [Vale's style documentation](https://vale.sh/docs/styles): + +```yaml +# Mendix/MyRule.yml +extends: substitution +message: "Use '%s' instead of '%s'" +level: error +ignorecase: true +swap: + 'bad term': 'good term' +``` + +## Overriding Microsoft Rules + +In `.vale.ini`: + +```ini +# Disable a Microsoft rule +Microsoft.Contractions = NO + +# Change severity +Microsoft.Wordiness = warning +``` diff --git a/.vale/styles/Mendix/SignIn.yml b/.vale/styles/Mendix/SignIn.yml new file mode 100644 index 00000000000..4b874d1c9bb --- /dev/null +++ b/.vale/styles/Mendix/SignIn.yml @@ -0,0 +1,19 @@ +# 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 +scope: + - paragraph + - heading + - list + - table + - blockquote +action: + name: replace +swap: + 'log in': 'sign in' + 'log out': 'sign out' + 'login to': 'sign in to' + 'logout': 'sign out' From 5971b6d6dc967c2c5a99cec85cc4c22d955c47cd Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 29 May 2026 13:47:53 +0200 Subject: [PATCH 2/2] Test for Vale --- .../docs/control-center/company/company-settings.md | 2 +- .../data-models/migrating-your-mendix-database.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/control-center/company/company-settings.md b/content/en/docs/control-center/company/company-settings.md index 4fc8d47d54f..66a0fb25480 100644 --- a/content/en/docs/control-center/company/company-settings.md +++ b/content/en/docs/control-center/company/company-settings.md @@ -41,7 +41,7 @@ After you click **Add security contact** and add the required **Name** and **Ema For an existing security contact, there are two menu options available: -* **Edit** — Edit the Security Contact's **Name**. +* **Edit** — Edit the Security Contact's **Name**. chekc * **Delete** — Delete the existing Security Contact. This is the first step in changing a validated Security Contact. After you make the deletion, you can add the new Security Contact. For more information on security issues, see [Security Advisories](/releasenotes/security-advisories/). diff --git a/content/en/docs/howto/data-models/migrating-your-mendix-database.md b/content/en/docs/howto/data-models/migrating-your-mendix-database.md index a55c44e2c57..86ebe1e1b63 100644 --- a/content/en/docs/howto/data-models/migrating-your-mendix-database.md +++ b/content/en/docs/howto/data-models/migrating-your-mendix-database.md @@ -7,7 +7,7 @@ description: "Describes how to migrate a non-PostgreSQL database to a PostgreSQL ## Introduction -This document explains how to migrate the data in an existing Mendix database to another Mendix database. This can be useful if you want to migrate from one type of database to another—for example, from MS SQL Server to PostgreSQL. +This document explains how to migrate the data in an existing Mendix database to anothdr Mendix database. This can be useful if you want to migrate from one type of database to another—for example, from MS SQL Server to PostgreSQL. After completing this how-to, you will know how to do the following: @@ -28,7 +28,7 @@ If you want to copy data to another app, Mendix recommends using the [Database R You can copy all the data from any Mendix-supported database management system to any other Mendix-supported database management system. For example, you can copy demo, test, and production databases from built-in to PostgreSQL, and from PostgreSQL to built-in. You can also migrate production data from SQL Server or Oracle (on-premises) to PostgreSQL in our cloud. -To do this, start your app on the database you want to copy the data to. This database should already exist and should be empty. To indicate which database the data should be copied from, you have to set some custom configuration settings. These custom settings identify the source database and give Mendix the authentication required to access the database. +To do this, start your app on the database you want to copy the data to. This database should already exist and should be empty. To indicate which database the data should be copied from, you have to set some custom configuration settings. These custom settings identify the source database and gicve Mendix the authentication required to access the database. These are the most commonly used custom settings for database migration: @@ -42,7 +42,7 @@ For more information and the full list of available settings, see [Runtime Custo These settings can be configured as follows: -* Studio Pro – in **App Explorer**, expand **App**, double-click **Settings**, edit a configuration, and go to the **Custom** tab: +* Studio Pro – in **App Explorer**, expand **App**, sdouble-click **Settings**, edit a configuration, and go to the **Custom** tab: {{< figure src="/attachments/howto/data-models/migrating-your-mendix-database/19398970.png" class="no-border" >}} @@ -75,7 +75,7 @@ To do this, follow these steps: * **Type** – **PostgreSQL** * **Database name** – *default* * **URL** – the URL for your local PostgreSQL server - * **User name** – the user name of a database administrator in your local PostgreSQL + * **User name** – the user name of a database admisnistrator in your local PostgreSQL * **Password** – the password for the user specified above {{< figure src="/attachments/howto/data-models/migrating-your-mendix-database/postgresql-config.png" class="no-border" >}} @@ -157,7 +157,7 @@ Below is general guidance on how to migrate a PostgreSQL database to a different #### General Guidance -The source database is a PostgreSQL database with the downloaded database from Mendix Cloud. The target non-PostgreSQL database should be completely empty; it should not contain any tables. In the Mendix app, the active configuration in **Settings** should point to the target database, and you should add the **Custom configuration** settings for the source PostgreSQL database as explained above in the overview. +The source database is a PostgreSQL database with the downloaded database from Mendix Cloud. The target non-PostgreSQL database should be completely empty; it should not contain any tables. In the Mendix app, the active configuration in **Settings** should point to the target database, andsd you should add the **Custom configuration** settings for the source PostgreSQL database as explained above in the overview. Once you have configured the Mendix app, run the application locally—it will automatically migrate the database schema and all the data from the source database to the target database. Before exporting the target database, you should always validate it by viewing the application in a browser. @@ -203,7 +203,7 @@ If you have a Mendix application running on SAP BTP with PostgreSQL as the datab 1. Sign in to the SAP BTP Cockpit. 2. Navigate to the subaccount containing the application from which you want to migrate the database. -3. In the service bindings of the application, find the postgreSQL DB or the shared postgreSQL DB. +3. In the service bindings of the application, find the postgreSQL DB or the shared postgreSQL DB. check 4. Click **Show sensitive data**. 5. Write down the values of the following properties in the `postgresql` service: * `dbname` – `{dbname}`