Style guides

You can define custom style rules for your project using YAML files with a subset of the Vale syntax.

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.

Supported Vale extension points

Writerside supports the following Vale extension points that you can use in the .wrs-style-guide.yaml file:

existence

Add the 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:

                    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 block to suggest replacements for tokens.

For example, to suggest replacing text box with field, add the following block:

                    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.

occurrence

Add the 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:

                    extends: occurrence
                    message: "This sentence has more than 3 commas. Consider rephrasing it."
                    scope: sentence
                    ignorecase: false
                    max: 3
                    token: ','
                

conditional

Add the 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:

                    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:

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.

For example, to avoid end punctuation in headings, add the following block:

                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:

                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.
action: name: remove
replace: Suggests replacements for the text.
action: name: replace params: - option1 - option2
convert: Converts the matched text to a lowercase space-delimited string.
action: name: convert params: - simple
edit: Suggests editing the matched text according to the specified parameter, for example, remove or replace.
action: name: edit params: - remove - '.?!'

11 February 2026