# Style guides You can define custom style rules for your project using YAML files with a subset of the [Vale syntax](https://vale.sh/docs/topics/styles/). Procedure: Create a project-level style guide * Right-click the project name and select `New | Writerside Style Guide File`. Writerside creates the `.wrs-style-guide.yaml` file in the project root with some sample rules. This file extends the Vale syntax and applies to all files across all project directories. > **Tip:** > You can add separate `.wrs-style-guide.yaml` files in subdirectories to override rules from parent directories. ## Supported Vale extension points Writerside supports the following [Vale extension points](https://vale.sh/docs/topics/styles/#extension-points) that you can use in the `.wrs-style-guide.yaml` file: ### existence Add the [existence](https://vale.sh/docs/topics/styles/#existence) block to find tokens that you want to avoid. For example, to avoid wordy phrases, such as, a number of and as a matter of fact, add the following block: ```YAML extends: existence message: Don't use '%s' ignorecase: true tokens: - a number of - as a matter of fact ``` Writerside will underline the specified words and offer to navigate to the rule definition. ### substitution Add the [substitution](https://vale.sh/docs/topics/styles/#substitution) block to suggest replacements for tokens. For example, to suggest replacing text box with field, add the following block: ```YAML extends: substitution message: Consider using '%s' instead of '%s' ignorecase: true level: suggestion swap: text box: field ``` Writerside will underline the specified words and offer a substitution. > **Tip:** > You can use [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) to find tokens by a pattern. If you want to provide several substitutions, separate them with a vertical bar `|`. > > > > > > For example, to suggest more neutral words like stop, exit, cancel, or end instead of kill, terminate, and abort, add the following block: > > > > > > > ```YAML > extends: substitution > message: "Consider using '%s' instead of '%s'." > level: warning > ignorecase: false > swap: > '(kill|terminate|abort)': stop|exit|cancel|end > ``` ### occurrence Add the [occurrence](https://vale.sh/docs/topics/styles/#occurrence) block to limit the number of occurrences and ensure that the token is not overused. Use `max` or `min` parameters to specify the maximum or minimum number of times a particular token can occur. For example, if you want to limit the number of commas in a sentence, add the following block: ```YAML extends: occurrence message: "This sentence has more than 3 commas. Consider rephrasing it." scope: sentence ignorecase: false max: 3 token: ',' ``` ### conditional Add the [conditional](https://vale.sh/docs/topics/styles/#conditional) block to ensure that some token implies the existence of another token. For example, to make sure that if your text contains "foo", it should also contain "bar" add the following block: ```YAML extends: conditional message: "'%s' has no period" ignorecase: true first: foo second: bar ``` Writerside will underline every occurrence of foo, unless there is also at least one occurrence of bar in the text. ## Scopes Use the `scope` argument to apply rules only to specific parts of the content. Writerside supports the following [scopes](https://vale.sh/docs/topics/scoping/): heading : Matches all `h1`, `h2`, `h3` and other heading tags. `heading.h1` matches only `h1` tags. The scope is supported in HTML and Markdown files. strong : Matches all bold (strong) parts of the content. The scope is supported in HTML and Markdown files. emphasis : Matches all italic (emphasized) parts of the content. The scope is supported in HTML and Markdown files. link : Matches all links. The scope is supported in HTML and Markdown files. sentence : Matches all sentences. This scope accepts any context. paragraph : Matches all paragraphs. This scope accepts any context. raw : Applies rules to the unprocessed content, independent of its structure or formatting. The scope is supported only in language-independent style files. > **Note:** > You can also specify a file extension in the scope. For example, the `heading.html` scope will apply rules to all HTML headings. For example, to avoid end punctuation in headings, add the following block: ```YAML extends: existence message: "Don't use end punctuation in headings." nonword: true scope: heading tokens: - '[a-z0-9][.?!](?:\s|$)' ``` ## Severity Use the `level` argument to specify the rule's severity level. Possible values are `suggestion`, `warning`, and `error`. For example, to mark a contraction as an error, use the following rule: ```YAML extends: substitution message: "Use '%s' instead of '%s'." level: error ignorecase: true swap: aren't: are not ``` ## Actions Writerside supports actions to specify the type of fix for the rule. An action must contain a `name` and an array of parameters. Writerside supports the following actions: remove : Suggests removing the specified text. : : : : : : : ```YAML : action: : name: remove : ``` replace : Suggests replacements for the text. : : : : : : : ```YAML : action: : name: replace : params: : - option1 : - option2 : ``` convert : Converts the matched text to a lowercase space-delimited string. : : : : : : : ```YAML : action: : name: convert : params: : - simple : ``` edit : Suggests editing the matched text according to the specified parameter, for example, remove or replace. : : : : : : : ```YAML : action: : name: edit : params: : - remove : - '.?!' : ```