Add latest changes from gitlab-org/gitlab@master

1 files changed, 58 insertions, 5 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 4fcdd8a1fb0..694acc16a97 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -393,15 +393,14 @@ merge request with new or changed docs is submitted, are:
 - [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48):
   Runs several tests on the content of the docs themselves:
   - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh)
-    checks that:
+    runs the following checks and linters:
     - All cURL examples use the long flags (ex: `--header`, not `-H`).
     - The `CHANGELOG.md` does not contain duplicate versions.
     - No files in `doc/` are executable.
     - No new `README.md` was added.
-  - [markdownlint](#markdownlint).
-  - Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
-    pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
-    (or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
+    - [markdownlint](#markdownlint).
+    - [Vale](#vale).
+  - Nanoc tests:
     - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L67)
       checks that all internal links (ex: `[link](../index.md)`) are valid.
     - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L69)
@@ -410,6 +409,60 @@ merge request with new or changed docs is submitted, are:
 - If any code or the `doc/README.md` file is changed, a full pipeline will run, which
   runs tests for [`/help`](#gitlab-help-tests).
 
+### Running tests & lint checks locally
+
+Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks
+and Nanoc tests locally.
+
+#### Nanoc tests
+
+To execute Nanoc tests locally:
+
+1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory.
+1. Run:
+
+   ```shell
+   # Check for broken internal links
+   bundle exec nanoc check internal_links
+
+   # Check for broken external links (might take a lot of time to complete).
+   # This test is set to be allowed to fail and is run only in the gitlab-docs project CI
+   bundle exec nanoc check internal_anchors
+   ```
+
+#### Lint checks
+
+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. Run:
+
+   ```shell
+   MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh
+   ```
+
+Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for.
+If you omit it completely, it will default to the `doc/` directory.
+The output should be similar to:
+
+```
+=> Linting documents at path /path/to/gitlab as <user>...
+=> Checking for cURL short options...
+=> Checking for CHANGELOG.md duplicate entries...
+=> Checking /path/to/gitlab/doc for executable permissions...
+=> Checking for new README.md files...
+=> Linting markdown style...
+=> Linting prose...
+✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
+✔ Linting passed
+```
+
+Note that this requires you to either have the required lint tools installed on your machine,
+or a working Docker installation, in which case an image with these tools pre-installed will be used.
+
+For more information on available linters refer to the [linting](#linting) section.
+
 ### Linting
 
 To help adhere to the [documentation style guidelines](styleguide.md), and improve the content