Add latest changes from gitlab-org/gitlab@master

1 files changed, 50 insertions, 26 deletions

diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index 58584b5168b..4f61b2424eb 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -13,7 +13,7 @@ processes similar to those used for code to maintain standards and quality of do
 We have tests:
 
 - To lint the words and structure of the documentation.
-- To check the validity of internal links within the documentation suite.
+- To check the validity of internal links in the documentation suite.
 - To check the validity of links from UI elements, such as files in `app/views` files.
 
 For the specifics of each test run in our CI/CD pipelines, see the configuration for those tests
@@ -51,7 +51,7 @@ To run tests locally, it's important to:
 Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh)
 script and can be executed as follows:
 
-1. Navigate to the `gitlab` directory.
+1. Go to the `gitlab` directory.
 1. Run:
 
    ```shell
@@ -113,7 +113,7 @@ Even if a specific broken link appears multiple times on a page, the test report
 
 To execute documentation link tests locally:
 
-1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory.
+1. Go to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory.
 1. Run the following commands:
 
    ```shell
@@ -243,7 +243,9 @@ This configuration is also used in build pipelines.
 
 You can use markdownlint:
 
-- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--).
+- On the command line, with either:
+  - [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli).
+  - [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2).
 - [In a code editor](#configure-editors).
 - [In a `pre-push` hook](#configure-pre-push-hooks).
 
@@ -281,7 +283,7 @@ You can use Vale:
 Vale returns three types of results:
 
 - **Error** - For branding guidelines, trademark guidelines, and anything that causes content on
-  the docs site to render incorrectly.
+  the documentation site to render incorrectly.
 - **Warning** - For general style guide rules, tenets, and best practices.
 - **Suggestion** - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list.
 
@@ -366,23 +368,34 @@ In general, follow these guidelines:
 
 ### Install linters
 
-At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in
-build pipelines:
+At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in build pipelines.
 
-1. Install `markdownlint-cli`:
+#### Install markdownlint
 
-   ```shell
-   yarn global add markdownlint-cli
-   ```
+You can install either `markdownlint-cli` or `markdownlint-cli2` to run `markdownlint`.
+
+To install `markdownlint-cli`, run:
+
+```shell
+yarn global add markdownlint-cli
+```
+
+To install `markdownlint-cli2`, run:
 
-   We recommend installing the version of `markdownlint-cli`
-   [used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building
-   the `image:docs-lint-markdown`.
+```shell
+yarn global add markdownlint-cli2
+```
+
+You should install the version of `markdownlint-cli` or `markdownlint-cli2`
+[used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building
+the `image:docs-lint-markdown`.
+
+#### Install Vale
 
-1. Install [`vale`](https://github.com/errata-ai/vale/releases). To install for:
+To install Install [`vale`](https://github.com/errata-ai/vale/releases) for:
 
-   - macOS using `brew`, run: `brew install vale`.
-   - Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases).
+- macOS using `brew`, run: `brew install vale`.
+- Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases).
 
 These tools can be [integrated with your code editor](#configure-editors).
 
@@ -391,16 +404,18 @@ These tools can be [integrated with your code editor](#configure-editors).
 It's important to use linter versions that are the same or newer than those run in
 CI/CD. This provides access to new features and possible bug fixes.
 
-To match the versions of `markdownlint-cli` and `vale` used in the GitLab projects, refer to the
+To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to the
 [versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml)
 when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD.
 
-| Tool               | Version   | Command                                                | Additional information |
-|--------------------|-----------|--------------------------------------------------------|------------------------|
-| `markdownlint-cli` | Latest    | `yarn global add markdownlint-cli`                     | None.                  |
-| `markdownlint-cli` | Specific  | `yarn global add markdownlint-cli@0.23.2`              | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. |
-| Vale               | Latest    | `brew update && brew upgrade vale`                     | This command is for macOS only. |
-| Vale               | Specific  | Not applicable.                                        | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). |
+| Tool                | Version  | Command                                   | Additional information                                                                       |
+|:--------------------|:---------|:------------------------------------------|:---------------------------------------------------------------------------------------------|
+| `markdownlint-cli`  | Latest   | `yarn global add markdownlint-cli`        | None.                                                                                        |
+| `markdownlint-cli2` | Latest   | `yarn global add markdownlint-cli2`       | None.                                                                                        |
+| `markdownlint-cli`  | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. |
+| `markdownlint-cli`  | Specific | `yarn global add markdownlint-cli@0.6.0`  | The `@` indicates a specific version, and this example updates the tool to version `0.6.0`.  |
+| Vale                | Latest   | `brew update && brew upgrade vale`        | This command is for macOS only.                                                              |
+| Vale                | Specific | Not applicable.                           | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases).           |
 
 ### Configure editors
 
@@ -410,6 +425,15 @@ command line.
 To configure markdownlint in your editor, install one of the following as appropriate:
 
 - Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint).
+  This package uses `markdownlint-cli` by default, but can be configured to use `markdownlint-cli2` with this
+  SublimeLinter configuration:
+
+  ```json
+  "markdownlint": {
+    "executable": [ "markdownlint-cli2" ]
+  }
+  ```
+
 - Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint).
 - Vim [ALE plugin](https://github.com/dense-analysis/ale).
 
@@ -463,7 +487,7 @@ Git [pre-push hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) a
 - Avoid pushing a branch if failures occur with these tests.
 
 [`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring,
-installing, and removing Git hooks easy.
+installing, and removing Git hooks simpler.
 
 Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml)
 file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project.
@@ -509,7 +533,7 @@ You can set Visual Studio Code to display only a subset of Vale alerts when view
 
 To display only a subset of Vale alerts when running Vale from the command line, use
 the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config`
-to point to the configuration file within the project, if needed:
+to point to the configuration file in the project, if needed:
 
 ```shell
 vale --config .vale.ini --minAlertLevel error doc/**/*.md