Create file to modify Vale's output

This commit creates a new .vale.py file in the root folder. It
breaks Vale's output apart into multiple lines, making it easier to
read the output. It also adds a new line that links back to the
style guide, explaining how to fix the error.

doc/.vale/gitlab/InternalLinkExtension.yml

@@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links
 level: error
 scope: raw
 raw:
-  - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*\)'
+  - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*?\)'

doc/README.md

@@ -25,7 +25,7 @@ No matter how you use GitLab, we have documentation for you.
 
 | Essential documentation                                                                                                              | Essential documentation                                                                                                    |
 |:-------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------|
-| [**User documentation**](user/index.md)<br/>Discover features and concepts for GitLab users.                                         | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. |
+| [**User documentation**](user/index.md)<br>Discover features and concepts for GitLab users.                                         | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. |
 | [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute!                                        | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started.                         |
 | [**Build an integration with GitLab**](#build-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our handy guides.       |
 | [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms.                            | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers.                                    |

scripts/lint-doc.sh

 #!/usr/bin/env bash
+set -o pipefail
 
 cd "$(dirname "$0")/.." || exit 1
 echo "=> Linting documents at path $(pwd) as $(whoami)..."
@@ -71,13 +72,14 @@ else
 function run_locally_or_in_docker() {
   local cmd=$1
   local args=$2
+  local pipe_cmd=$3
 
   if hash ${cmd} 2>/dev/null
   then
-    $cmd $args
+    $cmd $args | $pipe_cmd
   elif hash docker 2>/dev/null
   then
-    docker run -t -v ${PWD}:/gitlab -w /gitlab --rm registry.gitlab.com/gitlab-org/gitlab-docs/lint:latest ${cmd} ${args}
+    docker run -t -v ${PWD}:/gitlab -w /gitlab --rm registry.gitlab.com/gitlab-org/gitlab-docs/lint:latest ${cmd} ${args} | $pipe_cmd
   else
     echo
     echo "  ✖ ERROR: '${cmd}' not found. Install '${cmd}' or Docker to proceed." >&2
@@ -99,7 +101,7 @@ echo
 run_locally_or_in_docker 'markdownlint' "--config .markdownlint.json ${MD_DOC_PATH}"
 
 echo '=> Linting prose...'
-run_locally_or_in_docker 'vale' "--minAlertLevel error ${MD_DOC_PATH}"
+run_locally_or_in_docker 'vale' "--minAlertLevel error --output=JSON ${MD_DOC_PATH}" "ruby scripts/vale.rb"
 
 if [ $ERRORCODE -ne 0 ]
 then

scripts/vale.rb

+#!/usr/bin/env ruby
+#
+# Get the JSON output from Vale and format it in a nicer way
+# See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46725
+#
+# Usage:
+#   vale --output=JSON filename.md | ruby vale.rb
+#
+
+require 'json'
+
+input = ARGF.read
+data = JSON.parse(input)
+
+data.each_pair do |source, alerts|
+  alerts.each do |alert|
+    puts "#{source}:"
+    puts " Line #{alert['Line']}, position #{alert['Span'][0]} (rule #{alert['Check']})"
+    puts " #{alert['Severity']}: #{alert['Message']}"
+    puts " More information: #{alert['Link']}"
+    puts
+  end
+end