Adjust levels of Vale rules

Change the error levels of Vale style rules to pave the way for
requiring the Vale linter.

If a style rule has the `raw` scope, it is not currently possible to
disable the rule within a document using HTML/MDX comments. Further, a
rule with the `error` level causes Vale to exit with a nonzero error
code if a page violates the rule. As a result, this change makes the
following adjustments to the error levels of Vale style rules:

- `error`: styles where we want to ensure consistency/correctness, and
  where it is possible to disable the style using comments.
- `warning`: style rules that an author might need to ignore. This
  includes style rules with the `raw` scope, which cannot be disabled
  using comments.

For some style rules, change the scope from `raw` to another scope that
allows a docs author to disable the rule within a document using
HTML/MDX-style comments.

docs/vale-styles/3rd-party-products/aws-vs-amazon.yml

@@ -15,8 +15,7 @@
 #   /^AWS /{ print gensub(/AWS (.*)/,"  \"Amazon \\1\"","1") ": " $0}'
 extends: substitution
 message: "Incorrect AWS product name. Use %s instead of %s."
-scope: raw
-level: warning
+level: error
 ignorecase: true
 swap:
   "Amazon Account Management": AWS Account Management

docs/vale-styles/examples/teleport-accounts.yml

@@ -1,8 +1,8 @@
 extends: substitution
 message: "Incorrect example of a Teleport account URL. Use %s instead of %s."
-level: error
+scope: raw # So we can catch instances in code fences
+level: warning
 scope:
- - raw
 ignorecase: true
 swap:
   - 'https://(?!status|example)\w+.teleport\.sh': 'example.teleport.sh (or status.teleport.sh for the status page)'

docs/vale-styles/messaging/edition-names.yml

@@ -1,13 +1,7 @@
 extends: existence
 scope:
-  # Using the raw scope so we can catch instances in TabItem labels.
-  - raw
 message: '"%s" is no longer a recognized Teleport edition. Use "Teleport Enterprise (Self-Hosted)" or "Teleport Enterprise (Cloud)" instead. If the hosting type is not important in a given sentence, there is no need to specify it, and you can use "Teleport Enterprise".'
 level: error
-ignorecase: false
+ignorecase: true
 tokens:
-  # Adding the pattern '[ \t]*\n?[ \t]*' between each word since we are using the raw
-  # scope. This lets use catch violations that span two lines (i.e., that occupy
-  # the same paragraph).
-  - 'Teleport[ \t]*\n?[ \t]*Cloud'
-  - 'Teleport[ \t]*\n?[ \t]*Enterprise[ \t]*\n?[ \t]*Cloud'
+  - 'Teleport Enterprise Cloud'

docs/vale-styles/messaging/subjective-terms.yml

@@ -1,7 +1,7 @@
 extends: existence
 link: "https://github.com/gravitational/docs/blob/main/docs-contributors/style-guide.md#voice"
-message: "Avoid using '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead."
-level: error
+message: "Consider avoiding '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead."
+level: warning
 ignorecase: true
 tokens:
   - "powerful(ly)?"

docs/vale-styles/structure/architecture-h2.yml

@@ -6,7 +6,7 @@
 # This style defines a how-to guide as any guide that includes at least one H2
 # beginning "Step [0-9]". 
 extends: script
-level: error
+level: warning
 message: "In a how-to guide, the first H2-level section must be called `## How it works`. Use this section to include 1-3 paragraphs that describe the high-level architecture of the setup shown in the guide, i.e., which infrastructure components are involved and how they communicate. If there is already architectural information in the guide, include it in a `## How it works` section."
 scope: raw
 script: |

docs/vale-styles/structure/intro-paragraph.yml

@@ -1,7 +1,7 @@
 # This style enforces the presence of an introductory paragraph before the first
 # H2 of a docs page.
 extends: script
-level: error
+level: warning
 message: There must be a brief intro paragraph before the first H2-level section of a docs page. Use this to describe the purpose of the guide so a reader can determine whether they should continue reading. If the guide introduces a feature, describe the purpose and benefits of the feature. If there is already an "Introduction" H2 or similar, remove the heading.
 scope: raw
 script: |

docs/vale-styles/structure/step-numbering.yml

@@ -6,7 +6,7 @@
 # such as the presence of step headings in how-to guides and the formatting of
 # step headings.
 extends: script
-level: error
+level: warning
 message: Guides that include H2 sections named after numbered steps (e.g., "Step 1/5") must have the expected sequence of numbers and accurate total numbers of steps. This heading either has an unexpected step number or an unexpected total number of steps.
 scope: raw
 script: |