.vale.ini

StylesPath = .github/styles

# TODO(palfrey): Set this to `warning`, then to `suggestion` once Vale
#                    stabilizes in CI.
MinAlertLevel = error

Vocab = TraceMachina

Packages = alex, Microsoft, write-good

IgnoredScopes = code, tt, frontmatter

[formats]
mdx = md

[*.{md,mdx}]
BasedOnStyles = alex, Vale, Microsoft, write-good

# Ignore code blocks in Starlight's TabItems.
BlockIgnores = (?s)(<TabItem.*?>.*?```.*?```.*?</TabItem>)

# Skip URL targets in Markdown links — Vale.Terms shouldn't lint URLs,
# but does by default. The `(?<=\])` lookbehind narrows the pattern so
# it only matches the URL portion of `[link text](url)`.
TokenIgnores = ['"]\.\/[\w-]+\.mdx['"], (?<=\])\([^)]+\)

# Ignore filenames and directory names in tree visualizations.
BlockIgnores = (?s)(<FileTree>.*?</FileTree>)

# Too harsh. The `write-good.Passive` check already covers many cases.
write-good.E-Prime = NO

# Redundant. Covered by `write-good.Passive`.
Microsoft.Passive = NO

# We use typographic em-dashes with spaces for readability. The Microsoft
# style guide wants tight em-dashes; we don't.
Microsoft.Dashes = NO

# Pedantic style rules we don't want to enforce in technical docs:
Microsoft.Avoid = NO           # blanket bans on words like "backend"
Microsoft.HeadingColons = NO   # nitpicks heading punctuation
Microsoft.Contractions = NO    # "what's" vs "what is" is a tone choice
Microsoft.Foreign = NO         # allows "e.g." and "i.e."
Microsoft.Quotes = NO          # punctuation-inside-quotes is style
Microsoft.We = NO              # we use "we" in conversational tech docs

# Vale's built-in Terms rule does case-sensitive substitution. In tech
# docs, the same word can be a lowercase command (`bazel build`), a
# capitalised proper noun (Bazel), or a path fragment in a URL. Trying
# to enforce one form across all three is noisy and produces false
# positives in code blocks and URLs.
Vale.Terms = NO

# Microsoft.Auto wants "autodetects" instead of "auto-detects". Both are
# fine in technical prose.
Microsoft.Auto = NO