diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000000..7a493834295 --- /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.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: 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 + vale_flags: '--minAlertLevel=error' # Only flag errors, not warnings or suggestions + filter_mode: diff_context # Only check around changed lines, not entire files 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.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..7898abb2f4d --- /dev/null +++ b/.vale/SETUP.md @@ -0,0 +1,72 @@ +# 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 + +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 + +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/`. + + 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. + - 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..2e354293e87 --- /dev/null +++ b/.vale/styles/Mendix/Acronyms.yml @@ -0,0 +1,73 @@ +extends: conditional +message: "Define '%s' on first use." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#acronyms-and-initialisms +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..9e9f545aec8 --- /dev/null +++ b/.vale/styles/Mendix/Capitalization.yml @@ -0,0 +1,43 @@ +# 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)" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide/ +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..88a706d6f99 --- /dev/null +++ b/.vale/styles/Mendix/ClickOn.yml @@ -0,0 +1,20 @@ +# 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'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#click +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..30f787c6e21 --- /dev/null +++ b/.vale/styles/Mendix/ConditionalAdverbs.yml @@ -0,0 +1,16 @@ +# 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." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#conditional-adverbs +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..0bacbbd2405 --- /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.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#em-dash +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..070e5707004 --- /dev/null +++ b/.vale/styles/Mendix/Directions.yml @@ -0,0 +1,24 @@ +# 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'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#upperlowercase +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..946393fed06 --- /dev/null +++ b/.vale/styles/Mendix/Foreign.yml @@ -0,0 +1,16 @@ +# 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'." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#latin-abbreviations +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..abcfeeaa7eb --- /dev/null +++ b/.vale/styles/Mendix/HeadingTitleCase.yml @@ -0,0 +1,15 @@ +# 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 +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..1fbcdb86898 --- /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://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#hyperlinks +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..f2d9a5627c3 --- /dev/null +++ b/.vale/styles/Mendix/ListIntroductions.yml @@ -0,0 +1,17 @@ +# 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 (—)." +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#en-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..7599d77ab38 --- /dev/null +++ b/.vale/styles/Mendix/ProductNames.yml @@ -0,0 +1,33 @@ +# 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'" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide/ +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..6b8bf633f86 --- /dev/null +++ b/.vale/styles/Mendix/SignIn.yml @@ -0,0 +1,20 @@ +# 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)" +link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/terminology/#sign-insign-out +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' 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 456d180d020..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 @@ -4,8 +4,9 @@ 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 +## 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. @@ -85,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: @@ -156,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. @@ -179,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. @@ -291,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"). @@ -365,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/product-naming-guide.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md index c127a3a4eef..68eb2e845c0 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 1b1ef5124d8..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 @@ -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 @@ -124,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." @@ -454,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. @@ -502,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.