Merge pull request #874 from aireilly/vale-gitlab-report

Updating docs for Gitlab CI options

modules/user-guide/examples/gitlab-ci.yml

@@ -13,10 +13,10 @@ code_quality:
     - apk update && apk add git
     - vale sync # Pull down VRH rules package specified in vale.ini
   script:
-    # Get complete list of *.adoc files in the repo
-    - FILES=$(find . -type f -name "*.adoc")
-    # Clean out conditions for wider vale coverage
-    - sed -i -e 's/ifdef::.*\|ifndef::.*\|ifeval::.*\|endif::.*/ /' ${FILES}
+    # Get complete list of *.adoc files in the repository
+    - FILES=$(find . -type f -name "*.adoc") # <1>
+    # Clean out conditions for wider Vale coverage in AsciiDoc
+    - sed -i -e 's/ifdef::.*\|ifndef::.*\|ifeval::.*\|endif::.*/ /' ${FILES} # <2>
     # Use a template to rearrange the vale JSON output
     # Run vale with --no-exit to pass the build with errors
     - vale ${FILES} --minAlertLevel=error --glob='*.adoc' --output="$(pwd)/vale-json.tmpl" > gl-code-quality-report.json

modules/user-guide/pages/gitlab-code-quality-reports.adoc

@@ -27,6 +27,11 @@ The widget reports style compliance issues in the GitLab merge request interface
 ----
 include::example$gitlab-ci.yml[]
 ----
+<1> Update the `$FILES` step to match your documentation source type, for example, use `*.md` for markdown.
+<2> Optional.
+Vale does not lint inside AsciiDoc conditional statements unless you pass the conditional variables as link:https://vale.sh/docs/topics/scoping/#asciidoc[Asciidoctor attributes].
+You can bypass this limitation in the CI by temporarily removing `ifdef` and `ifeval` directives before linting with Vale.
+This step is only useful for AsciiDoc, and can be removed for other source formats.
 
 . Create a `vale-json.tmpl` file at the repository root:
 +