Merge pull request #9779 from circleci/DOCSS-1963-vale-rules

rosieyohannan · web-flow · commit f5513e99e1a4 · 2025-11-21T14:55:06.000Z
New linter rules
diff --git a/.vale.ini b/.vale.ini
@@ -4,7 +4,7 @@ Vocab = Docs
 
 MinAlertLevel = suggestion
 
-Packages = Readability
+Packages = Readability, AsciiDoc
 
 [asciidoctor]
 # attribute = value
@@ -18,4 +18,4 @@ experimental = YES
 attribute-missing = drop
 
 [*.adoc]
-BasedOnStyles = circleci-docs, Vale, Readability, Openly
+BasedOnStyles = circleci-docs, Vale, Readability, Openly, AsciiDoc
diff --git a/docs/guides/modules/about-circleci/pages/concepts.adoc b/docs/guides/modules/about-circleci/pages/concepts.adoc
@@ -1,6 +1,6 @@
 = Concepts
 :page-platform: Cloud, Server v4+
-:description: CircleCI concepts
+:page-description: CircleCI concepts
 :experimental:
 
 [#introduction]
diff --git a/docs/guides/modules/deploy/pages/deploy-service-update-to-aws-ecs.adoc b/docs/guides/modules/deploy/pages/deploy-service-update-to-aws-ecs.adoc
@@ -1,6 +1,6 @@
 = Deploy service update to AWS ECS
 :page-platform: Cloud, Server v4+
-:description: A how to guide for deploying changes to AWS ECS using CircleCI orbs.
+:page-description: A how to guide for deploying changes to AWS ECS using CircleCI orbs.
 :experimental:
 
 In this how-to guide, you will learn how to configure CircleCI to deploy to AWS ECS using CircleCI orbs.
diff --git a/docs/guides/modules/deploy/pages/publish-packages-to-packagecloud.adoc b/docs/guides/modules/deploy/pages/publish-packages-to-packagecloud.adoc
@@ -1,6 +1,6 @@
 = Publish packages to Packagecloud
 :page-platform: Cloud, Server v4+
-:description: How to publish packages to Packagecloud using CircleCI.
+:page-description: How to publish packages to Packagecloud using CircleCI.
 :experimental:
 
 In this how-to guide, you will learn how to configure CircleCI to publish packages to Packagecloud.
diff --git a/docs/guides/modules/execution-managed/pages/docker-to-machine.adoc b/docs/guides/modules/execution-managed/pages/docker-to-machine.adoc
@@ -1,6 +1,6 @@
 = Migrating from Docker to Machine
 :page-platform: Cloud, Server v4+
-:description: Best practices and considerations when migrating your executor from Docker to machine
+:page-description: Best practices and considerations when migrating your executor from Docker to machine
 :experimental:
 
 This page contains some general guidelines and considerations to make when moving from the Docker executor to machine, or vice versa.
diff --git a/docs/guides/modules/execution-managed/pages/hello-world-windows.adoc b/docs/guides/modules/execution-managed/pages/hello-world-windows.adoc
@@ -1,6 +1,6 @@
 = Hello world on Windows
 :page-platform: Cloud, Server v4+
-:description: First Windows project on CircleCI
+:page-description: First Windows project on CircleCI
 :experimental:
 
 This document describes how to get started with continuous integration on *Windows execution environments* on CircleCI. If this is your first time setting up CircleCI, we recommend checking out the xref:getting-started:getting-started.adoc[Getting Started guide].
diff --git a/docs/guides/modules/execution-managed/pages/using-linuxvm.adoc b/docs/guides/modules/execution-managed/pages/using-linuxvm.adoc
@@ -1,6 +1,6 @@
 = Using the Linux VM execution environment
 :page-platform: Cloud, Server v4+
-:description: Learn how to configure a your jobs to run in the Linux VM execution environment using the machine executor.
+:page-description: Learn how to configure a your jobs to run in the Linux VM execution environment using the machine executor.
 :experimental:
 
 You can run your jobs in the Linux VM (virtual machine) execution environment by using the machine executor and specifying a Linux image. Using the machine executor runs your jobs in a dedicated, ephemeral VM.
diff --git a/docs/guides/modules/execution-runner/pages/runner-feature-comparison-matrix.adoc b/docs/guides/modules/execution-runner/pages/runner-feature-comparison-matrix.adoc
@@ -1,6 +1,6 @@
 = Self-hosted runner feature comparison
 :page-platform: Cloud, Server v4+
-:description: A comparison table of the features available for CircleCI runners.
+:page-description: A comparison table of the features available for CircleCI runners.
 :experimental:
 
 This page offers a comparison of the features available for CircleCI machine runner vs. CircleCI container runner.
diff --git a/docs/guides/modules/getting-started/pages/language-javascript.adoc b/docs/guides/modules/getting-started/pages/language-javascript.adoc
@@ -1,6 +1,6 @@
 = Configure a Node.js application on CircleCI
 :page-platform: Cloud, Server v4+
-:description: Building and Testing with JavaScript and Node.js on CircleCI
+:page-description: Building and Testing with JavaScript and Node.js on CircleCI
 :experimental:
 
 This quickstart guide covers integrating a Node.JS project with CircleCI. This guide is designed to help you create a basic CircleCI configuration file to build, test and deploy your Node.JS project. After completing this quickstart you can edit and optimize the config to fit the requirements of your project.
diff --git a/docs/guides/modules/getting-started/pages/language-python.adoc b/docs/guides/modules/getting-started/pages/language-python.adoc
@@ -1,6 +1,6 @@
 = Configure a Python application on CircleCI
 :page-platform: Cloud, Server v4+
-:description: Continuous integration with Python on CircleCI
+:page-description: Continuous integration with Python on CircleCI
 :experimental:
 
 This quickstart guide covers integrating a Python project with CircleCI. This guide is designed to help you create a basic CircleCI configuration file to build, test and deploy your Python project. After completing this quickstart you can edit and optimize the config to fit the requirements of your project.
diff --git a/docs/guides/modules/integration/pages/authorize-google-cloud-sdk.adoc b/docs/guides/modules/integration/pages/authorize-google-cloud-sdk.adoc
@@ -1,6 +1,6 @@
 = Authorize Google Cloud SDK
 :page-platform: Cloud, Server v4+
-:description: How to authorize the Google Cloud SDK
+:page-description: How to authorize the Google Cloud SDK
 :experimental:
 
 This tutorial explains how to install and authorize the link:https://cloud.google.com/sdk/[Google Cloud SDK] in your primary container.
diff --git a/docs/guides/modules/integration/pages/jira-plugin.adoc b/docs/guides/modules/integration/pages/jira-plugin.adoc
@@ -1,6 +1,6 @@
 = Connect Jira with CircleCI
 :page-platform: Cloud
-:description: Connecting Jira with CircleCI
+:page-description: Connecting Jira with CircleCI
 :experimental:
 
 Integrate your CI/CD build and deployment status notifications directly into your Jira cards.
diff --git a/docs/guides/modules/integration/pages/oss.adoc b/docs/guides/modules/integration/pages/oss.adoc
@@ -1,6 +1,6 @@
 = Build open source projects
 :page-platform: Cloud
-:description: Best practices for building open source projects
+:page-description: Best practices for building open source projects
 :experimental:
 
 This document provides tips and best practices for building your open source project on CircleCI.
diff --git a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc
@@ -1,6 +1,6 @@
 = Version control system integration overview
 :page-platform: Cloud, Server
-:description: An overview guide to the version control systems you can integrate with CircleCI.
+:page-description: An overview guide to the version control systems you can integrate with CircleCI.
 :experimental:
 
 When you create a CircleCI project you will select a code repository to connect. The code in the repo you select is checked out when your pipelines trigger. CircleCI supports several code version control systems (VCS). This guide gives an overview of the features available to each VCS integration.
diff --git a/docs/guides/modules/migrate/pages/migrating-from-teamcity.adoc b/docs/guides/modules/migrate/pages/migrating-from-teamcity.adoc
@@ -1,6 +1,6 @@
 = Migrate from TeamCity
 :page-platform: Cloud, Server v4+
-:description: An overview of how to migrate from TeamCity to CircleCI.
+:page-description: An overview of how to migrate from TeamCity to CircleCI.
 :source-highlighter: pygments.rb
 :experimental:
 
diff --git a/docs/guides/modules/migrate/pages/migrating-from-travis.adoc b/docs/guides/modules/migrate/pages/migrating-from-travis.adoc
@@ -1,6 +1,6 @@
 = Migrate from Travis CI
 :page-platform: Cloud
-:description: An overview of how to migrate from Travis CI to CircleCI.
+:page-description: An overview of how to migrate from Travis CI to CircleCI.
 :experimental:
 
 This document provides an overview of how to migrate from Travis CI to CircleCI.
diff --git a/docs/guides/modules/orchestrate/pages/dynamic-config.adoc b/docs/guides/modules/orchestrate/pages/dynamic-config.adoc
@@ -1,6 +1,6 @@
 = Dynamic configuration overview
 :page-platform: Cloud, Server v4+
-:description: A guide to using CircleCI's dynamic configuration features
+:page-description: A guide to using CircleCI's dynamic configuration features
 :experimental:
 
 Dynamic configuration in CircleCI is the process of describing a pipeline in which the work done is dynamically determined. Dynamic configuration is flexible. The features described in this guide allow you to create a configuration to match the requirements of your specific project.
diff --git a/docs/guides/modules/plans-pricing/pages/credits.adoc b/docs/guides/modules/plans-pricing/pages/credits.adoc
@@ -1,6 +1,6 @@
 = Using credits
 :page-platform: Cloud
-:description: Learn about the CircleCI credits-based plan system.
+:page-description: Learn about the CircleCI credits-based plan system.
 :experimental:
 
 This document describes how to find the available resources regarding credits with CircleCI.
diff --git a/docs/guides/modules/security/pages/security-recommendations.adoc b/docs/guides/modules/security/pages/security-recommendations.adoc
@@ -1,6 +1,6 @@
 = Secure secrets handling
 :page-platform: Cloud, Server v4+
-:description: Learn how to handle secrets securely with CircleCI.
+:page-description: Learn how to handle secrets securely with CircleCI.
 :experimental:
 
 Many builds must reference secret values entrusted to CircleCI. CircleCI understands that security is critical to every organization's success. In addition to the work CircleCI does to keep your secrets safe, there are a few things you can do to help protect secrets at the boundary between CircleCI's systems and yours.
diff --git a/docs/guides/modules/security/pages/security-supply-chain.adoc b/docs/guides/modules/security/pages/security-supply-chain.adoc
@@ -1,6 +1,6 @@
 = Protecting against supply chain attacks
 :page-platform: Cloud, Server v4+
-:description: Protecting against supply chain attacks on CircleCI
+:page-description: Protecting against supply chain attacks on CircleCI
 :experimental:
 
 [#overview]
diff --git a/docs/guides/modules/test/pages/automate-llm-evaluation-testing-with-the-circleci-evals-orb.adoc b/docs/guides/modules/test/pages/automate-llm-evaluation-testing-with-the-circleci-evals-orb.adoc
@@ -1,6 +1,6 @@
 = Automate LLM evaluation testing with the CircleCI Evals orb
 :page-platform: Cloud, Server v4+
-:description: How to use CircleCI Evals orb.
+:page-description: How to use CircleCI Evals orb.
 :experimental:
 
 CircleCI supports running automatic large language model (LLM) evaluations and evaluation testing using your preferred GenAI application evaluation framework. Through declaring the necessary commands in your pipeline configuration you can run your LLM evaluations and test the results within your CircleCI pipeline.
diff --git a/docs/guides/modules/test/pages/collect-test-data.adoc b/docs/guides/modules/test/pages/collect-test-data.adoc
@@ -1,6 +1,6 @@
 = Collect test data
 :page-platform: Cloud, Server v4+
-:description: A guide to collecting test data in your CircleCI projects.
+:page-description: A guide to collecting test data in your CircleCI projects.
 :experimental:
 
 [#introduction]
diff --git a/docs/guides/modules/test/pages/testing-llm-enabled-applications-through-evaluations.adoc b/docs/guides/modules/test/pages/testing-llm-enabled-applications-through-evaluations.adoc
@@ -1,6 +1,6 @@
 = Testing LLM-enabled applications through evaluations
 :page-platform: Cloud, Server v4+
-:description: Docs page on setting up LLM evaluations in your CI/CD pipeline
+:page-description: Docs page on setting up LLM evaluations in your CI/CD pipeline
 :experimental:
 
 This page describes methods for testing applications powered by large language models (LLMs) through evaluations, including automating evaluations with CircleCI.
diff --git a/docs/guides/modules/toolkit/pages/api-intro.adoc b/docs/guides/modules/toolkit/pages/api-intro.adoc
@@ -1,6 +1,6 @@
 = API v2 introduction
 :page-platform: Cloud, Server v4+
-:description: Introduction to the CircleCI API
+:page-description: Introduction to the CircleCI API
 :experimental:
 
 The CircleCI API may be used to make API calls to interact with your pipelines, projects and orgs, including retrieving detailed information about users, jobs, workflows, and pipelines, as well as triggering pipelines. There are currently two supported API versions:
diff --git a/docs/guides/modules/toolkit/pages/managing-api-tokens.adoc b/docs/guides/modules/toolkit/pages/managing-api-tokens.adoc
@@ -1,6 +1,6 @@
 = Managing API tokens
 :page-platform: Cloud, Server v4+
-:description: How to assign scoped tokens for using the CircleCI API
+:page-description: How to assign scoped tokens for using the CircleCI API
 :experimental:
 
 To use the CircleCI API or view details about your pipelines, you will need API tokens with the appropriate permissions. This document describes the types of API tokens available, as well as how to create and delete them.
diff --git a/docs/guides/modules/toolkit/pages/sample-config.adoc b/docs/guides/modules/toolkit/pages/sample-config.adoc
@@ -1,6 +1,6 @@
 = Sample config.yml Files
 :page-platform: Cloud, Server v4+
-:description: Sample config.yml File
+:page-description: Sample config.yml File
 :experimental:
 :page-aliases: example-configs.adoc
 
diff --git a/docs/orbs/modules/author/pages/creating-orbs.adoc b/docs/orbs/modules/author/pages/creating-orbs.adoc
@@ -1,6 +1,6 @@
 = Publishing orbs
 :page-platform: Cloud
-:description: Publishing Orbs to the Orb Registry
+:page-description: Publishing Orbs to the Orb Registry
 :experimental:
 
 This guide covers the steps required to publish an orb.
diff --git a/docs/reference/modules/ROOT/pages/faq.adoc b/docs/reference/modules/ROOT/pages/faq.adoc
@@ -1,6 +1,6 @@
 = FAQ
 :page-platform: Cloud, Server v4+
-:description: Frequently asked questions about CircleCI
+:page-description: Frequently asked questions about CircleCI
 :experimental:
 
 This page answers frequently asked questions about the following CircleCI topics:
diff --git a/docs/reference/modules/ROOT/pages/variables.adoc b/docs/reference/modules/ROOT/pages/variables.adoc
@@ -1,6 +1,6 @@
 = Project values and variables
 :page-platform: Cloud, Server v4+
-:description: A list of all built-in variables for your CircleCI projects.
+:page-description: A list of all built-in variables for your CircleCI projects.
 :experimental:
 
 This page is a reference for all built-in values available for use in your CircleCI projects.
diff --git a/styles/AsciiDoc/ClosedAttributeBlocks.yml b/styles/AsciiDoc/ClosedAttributeBlocks.yml
@@ -0,0 +1,7 @@
+---
+extends: existence
+scope: raw
+level: error
+message: "Attribute block is not closed."
+raw:
+  - '(?<!.)(\[(?!{)[^\]\n]+)\n'
diff --git a/styles/AsciiDoc/ClosedIdQuotes.yml b/styles/AsciiDoc/ClosedIdQuotes.yml
@@ -0,0 +1,7 @@
+---
+extends: existence
+scope: raw
+level: error
+message: "Quoted ID value is not closed."
+raw:
+  - '(?<!.)\[id=(["\x27]).*(?<!\1)\]'
diff --git a/styles/AsciiDoc/ImageContainsAltText.yml b/styles/AsciiDoc/ImageContainsAltText.yml
@@ -0,0 +1,8 @@
+---
+extends: existence
+scope: raw
+level: error
+link: https://redhat-documentation.github.io/supplementary-style-guide/#cloud-services-images
+message: "Image is missing accessibility alt tags."
+raw:
+  - 'image::?.*\[\]'
diff --git a/styles/AsciiDoc/LinkContainsLinkText.yml b/styles/AsciiDoc/LinkContainsLinkText.yml
@@ -0,0 +1,10 @@
+---
+extends: existence
+scope: raw
+level: error
+ignorecase: true
+nonword: true
+link: https://redhat-documentation.github.io/supplementary-style-guide/#cloud-services-links-hypertext
+message: "Link is missing descriptive link text for accessibility."
+raw:
+  - 'link:.*(\[\]|\[click here\]|\[here\]|\[this\])'
diff --git a/styles/AsciiDoc/MatchingDotCallouts.yml b/styles/AsciiDoc/MatchingDotCallouts.yml
@@ -0,0 +1,47 @@
+---
+extends: script
+message: "Corresponding callout not found."
+level: warning
+link: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/
+scope: raw
+script: |
+  text := import("text")
+  matches := []
+
+  // clean out multi-line comments
+  scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "")
+  //add a newline, it might be missing
+  scope += "\n"
+
+  num_codeblock_callouts := 0
+  num_callouts := 0
+  codeblock_callout_regex := ".+<(\\.)>"
+  callout_regex := "^<(\\.)>"
+
+  for line in text.split(scope, "\n") {
+    // trim trailing whitespace
+    line = text.trim_space(line)
+    if text.re_match(codeblock_callout_regex, line) {
+      //restart for new listingblock
+      num_callouts = 0
+      //account for lines with multiple callouts
+      num_callouts_in_line := text.count(line, "<.>")
+      if num_callouts_in_line > 1 {
+        num_codeblock_callouts = num_codeblock_callouts + num_callouts_in_line
+      } else {
+        num_codeblock_callouts++
+      }
+    }
+
+    if text.re_match(callout_regex, line) {
+      num_callouts++
+      if num_callouts > num_codeblock_callouts {
+        start := text.index(scope, line)
+        matches = append(matches, {begin: start, end: start + len(line)})
+      }
+      if num_callouts == num_codeblock_callouts {
+        num_callouts = 0
+        num_codeblock_callouts = 0
+      }
+    }
+  }
diff --git a/styles/AsciiDoc/MatchingNumberedCallouts.yml b/styles/AsciiDoc/MatchingNumberedCallouts.yml
@@ -0,0 +1,62 @@
+---
+extends: script
+message: "Corresponding callout not found."
+level: warning
+link: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/
+scope: raw
+script: |
+  text := import("text")
+  matches := []
+
+  // clean out multi-line comments
+  scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "")
+  //add a newline, it might be missing
+  scope += "\n"
+
+  codeblock_callout_regex := ".+(<\\d+>)+"
+  callout_regex := "^<(\\d+)>"
+  codeblock_callouts := []
+  inside := false
+  found := false
+  num_callouts := 0
+
+  num_lines := len(text.split(scope, "\n"))
+
+  for line in text.split(scope, "\n") {
+    // trim trailing whitespace
+    line = text.trim_space(line)
+    if text.re_match(codeblock_callout_regex, line) {
+      inside = true
+      //account for lines with multiple callouts
+      for i := 1; i < num_lines; i++ {
+        //text.contains must be str, not regex
+        str := "<" + i + ">"
+        if text.contains(line, str) {
+          codeblock_callouts = append(codeblock_callouts, i)
+        }
+      }
+    } else if text.re_match(callout_regex, line) {
+      inside = false
+      found = false
+      num_callouts = 1
+      for i in codeblock_callouts {
+        //cast int > string
+        j := text.itoa(i)
+        str := "<" + j + ">"
+        if text.contains(line, str) {
+          //setting found allows us to loop through the list of possible matches
+          found = true
+        }
+        num_callouts++
+      }
+      if !found {
+        start := text.index(scope, line)
+        matches = append(matches, {begin: start, end: start + len(line)})
+      }
+    } else if codeblock_callouts && inside == false {
+      //cycled through num_callouts, reset for next codeblock
+      if num_callouts == len(codeblock_callouts) {
+        codeblock_callouts = []
+      }
+    }
+  }
diff --git a/styles/AsciiDoc/SequentialNumberedCallouts.yml b/styles/AsciiDoc/SequentialNumberedCallouts.yml
diff --git a/styles/AsciiDoc/UnsetAttributes.yml b/styles/AsciiDoc/UnsetAttributes.yml
diff --git a/styles/AsciiDoc/ValidAdmonitionBlocks.yml b/styles/AsciiDoc/ValidAdmonitionBlocks.yml
diff --git a/styles/AsciiDoc/ValidCodeBlocks.yml b/styles/AsciiDoc/ValidCodeBlocks.yml
diff --git a/styles/AsciiDoc/ValidConditions.yml b/styles/AsciiDoc/ValidConditions.yml
diff --git a/styles/AsciiDoc/ValidTableBlocks.yml b/styles/AsciiDoc/ValidTableBlocks.yml
diff --git a/styles/circleci-docs/CodeBlockTitles.yml b/styles/circleci-docs/CodeBlockTitles.yml
diff --git a/styles/circleci-docs/HeadingBackticks.yml b/styles/circleci-docs/HeadingBackticks.yml
diff --git a/styles/circleci-docs/ImageTitles.yml b/styles/circleci-docs/ImageTitles.yml
diff --git a/styles/circleci-docs/ListPunctuation.yml b/styles/circleci-docs/ListPunctuation.yml
diff --git a/styles/circleci-docs/PageDescriptionLength.yml b/styles/circleci-docs/PageDescriptionLength.yml
diff --git a/styles/circleci-docs/PageTitleLength.yml b/styles/circleci-docs/PageTitleLength.yml
diff --git a/styles/circleci-docs/TableTitles.yml b/styles/circleci-docs/TableTitles.yml
diff --git a/styles/circleci-docs/XrefTitleCase.yml b/styles/circleci-docs/XrefTitleCase.yml
