From c72d04e98510f189a0a5f2bb133395d8b07f17f1 Mon Sep 17 00:00:00 2001 From: Amy Qualls <aqualls@gitlab.com> Date: Sun, 4 Jun 2023 22:28:24 +0000 Subject: [PATCH] Document non-Vale/markdownlint tests, testing pg The docs-lint markdown job is sneaky, and runs an additional check that we don't talk much about. --- doc/development/documentation/testing.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 4a7e206da201a..31e495fe9a46c 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -48,6 +48,24 @@ To run tests locally, it's important to: ### Lint checks +Merge requests containing changes to Markdown (`.md`) files run a `docs-lint markdown` +job. This job runs `markdownlint`, and a set of tests from +[`/scripts/lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh) +that look for page content problems that Vale and markdownlint cannot test for. +The job fails if any of these tests fail: + +- Curl (`curl`) commands must use long-form options (`--header`) instead of short options, like `-h`. +- Documentation pages must contain front matter indicating ownership of the page. +- Non-standard Unicode space characters (NBSP, NNBSP, ZWSP) must not be used in documentation, + because they can cause irregularities in search indexing and grepping. +- `CHANGELOG.md` must not contain duplicate versions. +- No files in the `doc/` directory may be executable. +- Use `index.md` instead of `README.md`. +- Directories and file names must use underscores instead of dashes. +- Directories and file names must be in lower case. + +#### Run lint checks locally + 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 with the help of a Rake task as follows: -- GitLab