diff --git a/.github/styles/UmbracoDocs/Acronyms.yml b/.github/styles/UmbracoDocs/Acronyms.yml index bb4c8522791..5a6c81e23e0 100644 --- a/.github/styles/UmbracoDocs/Acronyms.yml +++ b/.github/styles/UmbracoDocs/Acronyms.yml @@ -1,95 +1,123 @@ +--- extends: conditional -message: "'%s' has no definition" -level: error +message: "'%s' has no definition." +description: > + Ensures that all acronyms used in the documentation are clearly defined. +link: https://docs.umbraco.com/contributing/documentation/style-guide#acronyms scope: text +level: error ignorecase: false -# Ensures that the existence of 'first' implies the existence of 'second'. -# Require leading whitespace to avoid matching on URL substrings eg https://www.youtube.com/embed/OUD-PbWESAs?rel=0 +# If an uppercase acronym of 3-5 letters is found (first), +# require a definition (second) somewhere nearby. first: '\b([A-Z]{3,5})\b' second: '([A-Z]{3,5}): (?:\b[A-Z][a-z]+ )+|(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' -# ... with the exception of these: +# ... with the exception of these. Sorted alphabetically for easier maintenance. exceptions: - - ABC - - ADD - - ALT - - HTML - - JSON - - CSS - - API - - URL - - UDI - - URI - - NET - - MVC - - GET - - ASP - - ADO - - REST - - HTTP - - HTTPS - - CURL - - BASE - - UDA - - CLI - - KUDU - - XML - - PATH - - SQL - - SHIFT - - POST - - GUID - - UWP - - HAL - - LINK - - DLL - - CMS - - ONLY - - IIS - - DNS - - DOM - - XSLT - - AJAX - - YAML - - PNG - - ISO - - PDF - - DXP - - FAQ - - DIBS - - VAT - - SKU - - UTC - - HEX - - RGBA - - IDE - - CPU - - RAM - - CNAME - - AAAA - - TXT - - PUT - - DELETE - - ZIP - - CTRL - - SPACE - - ENTER - - VIP - - DEBUG - - INFO - - TEMP - - GIF - - GDPR - - NPM - - SVG - - DHL - - UUI - - MDN - - JPG - - JPEG - - BCC - - SSD - - ASCII - - CMD - - NGINX - - SDK - - SMTP + - AAAA # IPv6 address record (DNS) + - ADD # + - ADO # ActiveX Data Objects + - AJAX # Asynchronous JavaScript and XML + - ALT # Alternative text (images) + - API # Application Programming Interface + - ASCII # American Standard Code for Information Interchange + - ASP # Active Server Pages + - BCC # Blind Carbon Copy (email) + - CD # Continuous Delivery + - CDN # Content Delivery Network + - CI # Continuous Integration + - CLI # Command Line Interface + - CMD # Command (Windows shell) + - CMS # Content Management System + - CPU # Central Processing Unit + - CSS # Cascading Style Sheets + - CTRL # Control (Keyboard key) + - CURL # Client URL + - DELETE # HTTP DELETE method + - DHL # International Shipping brand + - DIBS # DIBS by Nets + - DNS # Domain Name System + - DOM # Document Object Model + - DXP # Digital Experience Platform + - EOL # End of Life + - FAQ # Frequently Asked Questions + - FTP # File Transfer Protocol + - GDPR # General Data Protection Regulation + - GET # HTTP GET method + - GIF # Graphics Interchange Format + - GUI # Graphical user interface + - GUID # Globally Unique Identifier + - HAL # Hypertext Application Language + - HASH # Cryptographic hash + - HEX # Hexadecimal + - HTML # HyperText Markup Language + - HTTP # HyperText Transfer Protocol + - HTTPS # HyperText Transfer Protocol Secure + - IaaS # Infrastructure as a Service + - IDE # Integrated Development Environment + - IIS # Internet Information Services + - INFO # Information + - ISO # International Organization for Standardization + - JPG # Joint Photographic Experts Group + - JPEG # Joint Photographic Experts Group + - JSON # JavaScript Object Notation + - JSONP # JSON with Padding + - JS # JavaScript + - JWT # JSON Web Token + - KUDU # Azure deployment engine + - LDAP # Lightweight Directory Access Protocol + - LINK # + - MIT # Open-source software license developed at the Massachusetts Institute of Technology (MIT) + - MDN # Mozilla Developer Network + - MFA # Multi-factor Authentication + - MVC # Model-View-Controller + - NET # .NET Framework + - NGINX # Engine X (web server) + - NPM # Node Package Manager + - OAuth # Open Authorization + - ONLY # + - ORM # Object-Relational Mapping + - PaaS # Platform as a Service + - PATH # file system path + - PDF # Portable Document Format + - PNG # Portable Network Graphics + - POST # HTTP POST method + - PUT # HTTP PUT method + - RAM # Random Access Memory + - REST # Representational State Transfer + - RGBA # Red Green Blue Alpha (color model) + - RPG # Role-Playing Game + - RTX # Ray Tracing Texel eXtreme (NVIDIA tech) + - SaaS # Software as a Service + - SDK # Software Development Kit + - SEO # Search Engine Optimization + - SHIFT # Keyboard key + - SPACE # Keyboard key + - SKU # Stock Keeping Unit + - SMTP # Simple Mail Transfer Protocol + - SQL # Structured Query Language + - SSD # Solid State Drive + - SSL # Secure Sockets Layer + - SVG # Scalable Vector Graphics + - TCP # Transmission Control Protocol + - TEMP # Temporary + - TS # TypeScript + - TXT # Text (file format) + - TLS # Transport Layer Security + - UDA # Files for Umbraco project's metadata + - UDI # Unique Device Identifier + - UI # User Interface + - URI # Uniform Resource Identifier + - URL # Uniform Resource Locator + - UTC # Coordinated Universal Time + - UUID # Universally Unique Identifier + - UWP # Universal Windows Platform + - UX # User Experience + - VAL # + - VAT # Value-Added Tax + - VIP # Very Important Person + - WYSIWYG # What You See Is What You Get + - XML # Extensible Markup Language + - XSLT # Extensible Stylesheet Language Transformations + - XSS # Cross-Site Scripting + - YAML # YAML file + - ZIP # ZIP file format diff --git a/.github/styles/UmbracoDocs/Brands.yml b/.github/styles/UmbracoDocs/Brands.yml index 1d78bf2adf7..f7381b8cb58 100644 --- a/.github/styles/UmbracoDocs/Brands.yml +++ b/.github/styles/UmbracoDocs/Brands.yml @@ -1,13 +1,31 @@ --- extends: substitution -message: "We prefer %s over '%s.'" +message: "Use '%s' instead of '%s' for brand consistency." +description: > + Ensures consistent capitalization of brand and product names. + This rule ignores matches inside markdown links and inline code to prevent false warnings. +link: https://docs.umbraco.com/contributing/documentation/style-guide#brands level: warning +scope: text +ignorecase: true +# Sorted alphabetically for easier maintenance. swap: - '(? + Flags words and phrases that express opinion, exaggeration, or assumptions. These can make documentation feel biased, subjective, or unclear. +link: https://docs.umbraco.com/contributing/documentation/style-guide#avoid-punctuation-in-headings level: warning +ignorecase: true +# Sorted alphabetically for easier maintenance. +# Uses regex patterns with \b for whole word matching. +# The pattern for 'simple' excludes common technical terms to reduce false positives. tokens: - actually - aptly @@ -37,7 +43,7 @@ tokens: - remarkably - several - significantly - - simple + - '\bsimple\b(?! (Mail|Message|Object|Protocol|Transfer|Markup))' - simply - substantially - surprisingly diff --git a/.github/styles/UmbracoDocs/HeadingsPunctuation.yml b/.github/styles/UmbracoDocs/HeadingsPunctuation.yml index a4b839c93a5..e1f45188d1f 100644 --- a/.github/styles/UmbracoDocs/HeadingsPunctuation.yml +++ b/.github/styles/UmbracoDocs/HeadingsPunctuation.yml @@ -1,8 +1,10 @@ --- extends: existence -message: Do not use '%s' at the end of headings -link: https://github.com/cockroachdb/docs/blob/master/STYLE.md#capitalization-and-punctuation +message: "Do not use '%s' at the end of heading." +description: > + Checks headings to ensure they do not end with punctuation. +link: https://docs.umbraco.com/contributing/documentation/style-guide#avoid-punctuation-in-headings scope: heading level: warning raw: - - '(?:\:|\.)$' \ No newline at end of file + - '(?:[.:;!…])$' \ No newline at end of file diff --git a/.github/styles/UmbracoDocs/LinkTextClarity.yml b/.github/styles/UmbracoDocs/LinkTextClarity.yml new file mode 100644 index 00000000000..dbcec914e4b --- /dev/null +++ b/.github/styles/UmbracoDocs/LinkTextClarity.yml @@ -0,0 +1,11 @@ +--- +extends: existence +message: "Avoid generic link text like '%s'. Use descriptive link text instead." +description: > + Descriptive link text improves accessibility and SEO. +level: warning +tokens: + - 'click here' + - 'read more' + - 'more info' + - '\bhere\b' diff --git a/.github/styles/UmbracoDocs/ListStart.yml b/.github/styles/UmbracoDocs/ListStart.yml index 0513d3aacc9..a7066bb844c 100644 --- a/.github/styles/UmbracoDocs/ListStart.yml +++ b/.github/styles/UmbracoDocs/ListStart.yml @@ -1,8 +1,12 @@ +--- extends: existence -message: "Start each option with a capital letter." -link: https://github.com/testthedocs/vale-styles/blob/master/OpenStack/ListStart.yml -level: warning +message: "List items should start with a capital letter, unless they begin with an inline code or a URL." +description: > + Ensures that each list item starts with a capital letter, + unless the item begins with inline code or a URL. +link: https://docs.umbraco.com/contributing/documentation/style-guide#use-lists-when-listing-more-than-2-items-steps scope: list +level: warning nonword: true tokens: - - '^[a-z].+' \ No newline at end of file + - '^(?!\[|_)[a-z].+' \ No newline at end of file diff --git a/.github/styles/UmbracoDocs/Names.yml b/.github/styles/UmbracoDocs/Names.yml index 8bb91063e91..81712549f05 100644 --- a/.github/styles/UmbracoDocs/Names.yml +++ b/.github/styles/UmbracoDocs/Names.yml @@ -1,14 +1,19 @@ +--- extends: substitution -message: "We prefer %s over '%s'" +message: "Use '%s' instead of '%s' for consistency." +description: > + Ensures consistent capitalization and formatting of common terms and acronyms. +link: https://docs.umbraco.com/contributing/documentation/style-guide#names level: warning +scope: paragraph swap: - '(?:(? + Detects repeated words like 'the the'. +alpha: true +level: warning +tokens: + - '[^\s]+' + diff --git a/.github/styles/UmbracoDocs/SentenceLength.yml b/.github/styles/UmbracoDocs/SentenceLength.yml index bf9876194a8..e001bfd020e 100644 --- a/.github/styles/UmbracoDocs/SentenceLength.yml +++ b/.github/styles/UmbracoDocs/SentenceLength.yml @@ -1,5 +1,10 @@ -message: "Write shorter sentences (less than 25 words)." +--- extends: occurrence +message: "Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content." +description: > + Shorter sentences improve readability and clarity in documentation. + To avoid false positives in note or warning tags, add blank lines around the block content. +link: https://docs.umbraco.com/contributing/documentation/style-guide#avoid-long-sentences scope: sentence level: warning max: 25 diff --git a/.github/styles/UmbracoDocs/Spacing.yml b/.github/styles/UmbracoDocs/Spacing.yml index 61f3f8b3fbb..0e96ffed8b8 100644 --- a/.github/styles/UmbracoDocs/Spacing.yml +++ b/.github/styles/UmbracoDocs/Spacing.yml @@ -1,5 +1,11 @@ +--- extends: existence message: "'%s' should have one space." +description: > + Ensures there is exactly one space after punctuations. Flags both extra spaces and missing spaces + after punctuation marks to improve consistency and readability. +link: https://docs.umbraco.com/contributing/documentation/style-guide#avoid-double-spacing level: error tokens: - - '[.?!] {2,}[A-Z]' \ No newline at end of file + - '[.?!,;:] {2,}' # double space after punctuation + - '[.?!,;:](?!\s)[A-Z]' # missing space after punctuation \ No newline at end of file diff --git a/.github/styles/UmbracoDocs/Terms.yml b/.github/styles/UmbracoDocs/Terms.yml index b230572ff62..9860a54e7eb 100644 --- a/.github/styles/UmbracoDocs/Terms.yml +++ b/.github/styles/UmbracoDocs/Terms.yml @@ -1,17 +1,19 @@ --- extends: substitution -message: "We prefer %s over '%s.'" +message: "Use %s instead of '%s' for consistency." +description: > + Replaces outdated, unclear, or informal terms with more inclusive or formal alternatives + for clarity, accessibility, and consistency across Umbraco documentation. +link: https://docs.umbraco.com/contributing/documentation/style-guide#terms-general level: warning ignorecase: true swap: - blacklist: "'deny list'" - whitelist: "'allow list'" - black list: "'deny list'" - white list: "'allow list'" - master: "'primary'" - slave: "'secondary'" - etc.: "'and so on'" - \b(?:eg|e\.g\.)[\s,]: "'for example'" - \b(?:ie|i\.e\.)[\s,]: "'that is'" - aka: "'also known as" - docs: "'documentation'" + '\bmaster\b(?!\s(?:branch|template|templates|templating|view|views|layout))': "'primary'" # Avoid false positives in valid Git and template contexts + 'slave': "'secondary'" + 'black\s?list': "'deny list'" + 'white\s?list': "'allow list'" + 'etc\.': "'and so on'" + '\b(?:eg|e\.g\.)[\s,]': "'for example'" + '\b(?:ie|i\.e\.)[\s,]': "'that is'" + 'aka': "'also known as'" + 'docs': "'documentation'" diff --git a/.github/styles/UmbracoDocs/UmbracoTerms.yml b/.github/styles/UmbracoDocs/UmbracoTerms.yml index 47b0a8be737..17d6cbac889 100644 --- a/.github/styles/UmbracoDocs/UmbracoTerms.yml +++ b/.github/styles/UmbracoDocs/UmbracoTerms.yml @@ -1,19 +1,24 @@ --- extends: substitution -message: "We prefer %s over '%s.'" +message: "Use %s instead of '%s.' for consistency." +description: > + Ensures consistent naming and capitalization for Umbraco-specific terms, + avoiding false positives in paths, URLs, or inline code. +link: https://docs.umbraco.com/contributing/documentation/style-guide#umbraco-terms level: warning swap: - document type: "'Document Type'" - document-type: "'Document Type'" - doc type: "'Document Type'" - doc-type: "'Document Type'" - data-type: "'Data Type'" - data type: "'Data Type'" - '(?