Add Vale as a documentation linter

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  lint:
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Install Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '2.7'
+      - name: Install asciidoctor gem
+        run: |
+          gem install asciidoctor
+      - name: Install Vale
+        run: |
+          curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v2.6.8
+          export PATH="./bin:$PATH"
+      - name: Lint
+        run: |
+          ./bin/vale docs/**

.vale.ini

@@ -0,0 +1,14 @@
+# Vale configuration file.
+#
+# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration.
+
+StylesPath = docs/.vale
+MinAlertLevel = suggestion
+WordTemplate = \s(?:%s)\s
+
+[*]
+BlockIgnores = (?s) (\+{4,}.*?\+{4,})
+TokenIgnores = (\$+[^\n$]+\$+)
+
+[*.adoc]
+BasedOnStyles = asciidoctor

docs/.vale/asciidoctor/FirstPerson.yml

@@ -0,0 +1,16 @@
+---
+# Warning: asciidoctor.FirstPerson
+#
+# Checks for use of first person pronouns.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.'
+level: warning
+ignorecase: true
+scope: paragraph
+tokens:
+  - '\bI[ ,;:?!"]|\bI\x27.{1,2}'
+  - me
+  - myself
+  - mine

docs/.vale/asciidoctor/InclusionCultural.yml

@@ -0,0 +1,15 @@
+---
+# Warning: asciidoctorInclusionCultural
+#
+# Suggests alternatives for words that are culturally inappropriate.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+level: warning
+ignorecase: true
+swap:
+  blacklist(?:ed|ing|s)?: denylist
+  whitelist(?:ed|ing|s)?: allowlist
+  \smaster: primary, main
+  slave: secondary

docs/.vale/asciidoctor/InclusionGender.yml

@@ -0,0 +1,17 @@
+---
+# Suggestion: asciidoctor.InclusionGender
+#
+# Suggests alternatives for words that are gender-specific.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+level: suggestion
+ignorecase: true
+swap:
+  mankind: humanity, people
+  manpower: GitLab team members
+  he: they
+  his: their
+  she: they
+  hers: their

docs/.vale/asciidoctor/Repetition.yml

@@ -0,0 +1,12 @@
+---
+# Error: asciidoctor.Repetition
+#
+# Checks for duplicate words, like `the the` or `and and`.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: repetition
+message: '"%s" is repeated.'
+level: error
+alpha: true
+tokens:
+  - '[^\s]+'

docs/.vale/asciidoctor/SentenceLength.yml

@@ -0,0 +1,12 @@
+---
+# Warning: asciidoctor.SentenceLength
+#
+# Counts words in a sentence and alerts if a sentence exceeds 25 words.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: occurrence
+message: 'Shorter sentences improve readability (max 25 words).'
+scope: sentence
+level: warning
+max: 25
+token: \b(\w+)\b

docs/.vale/asciidoctor/SentenceSpacing.yml

@@ -0,0 +1,16 @@
+---
+# Error: asciidoctor.SentenceSpacing
+#
+# Checks for the following in common content scenarios:
+#
+# - No spaces.
+# - More than one space.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: '"%s" must contain one and only one space.'
+level: error
+nonword: true
+tokens:
+  - '[a-z][.?!,][A-Z]'
+  - '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]'

docs/.vale/asciidoctor/Simplicity.yml

@@ -0,0 +1,16 @@
+---
+# Suggestion: asciidoctor.Simplicity
+#
+# Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.'
+level: suggestion
+ignorecase: true
+tokens:
+  - easy
+  - easily
+  - handy
+  - simple
+  - simply

docs/.vale/asciidoctor/Spelling.yml

@@ -0,0 +1,17 @@
+---
+# Warning: asciidoctor.Spelling
+#
+# Checks for possible spelling mistakes in content, not code. May find false positives
+# due to links using angle brackets: <https://example.com>. These can be ignored.
+#
+# If a word is flagged as a spelling mistake incorrectly, such as a product name,
+# you can submit an PR to update `spelling-exceptions.txt` with the missing word.
+# Commands, like `git clone` must use backticks, and must not be added to the
+# exceptions.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: spelling
+message: 'Spelling check: "%s"?'
+level: warning
+ignore:
+  - asciidoctor/spelling-exceptions.txt

docs/.vale/asciidoctor/Substitutions.yml

@@ -0,0 +1,27 @@
+---
+# Error: asciidoctor.Substitutions
+#
+# Checks for use of some of the top misused terms in the Asciidoctor community.
+# For substitutions only flagged as warnings, see SubstitutionWarning.yml
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use "%s" instead of "%s".'
+level: error
+ignorecase: true
+nonword: false
+scope: text
+swap:
+  asciidoctorj: AsciidoctorJ
+  asciidoctor-reveal.js: Asciidoctor reveal.js
+  reveal.js: reveal.js
+  netlify: Netlify
+  bundler: Bundler
+  javascript: JavaScript
+  node: Node
+  node.js: Node.js
+  npm: npm
+  '[^\.-]js': JS
+  ruby: Ruby
+  asciidoc: AsciiDoc
+  asciidoctor: Asciidoctor

docs/.vale/asciidoctor/SubstitutionsWarning.yml

@@ -0,0 +1,21 @@
+---
+# Warning: asciidoctor.SubstitutionWarning
+#
+# Warns against using common shorthand for terms.
+# For substitutions flagged as errors, see Substitutions.yml
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'If possible, use "%s" instead of "%s".'
+link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+level: warning
+ignorecase: true
+swap:
+  code base: codebase
+  config: configuration
+  distro: distribution
+  file name: filename
+  filesystem: file system
+  info: information
+  repo: repository
+  utilize: use

docs/.vale/asciidoctor/TitleCapitalization.yml

@@ -0,0 +1,15 @@
+---
+# Warning: asciidoctor.TitleCapitalization
+#
+# Checks the capitalization for the page title (i.e., doctitle).
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: capitalization
+message: "'%s' should be in title case"
+level: error
+scope: heading.h1
+match: $title
+style: Chicago
+exceptions:
+  - npm
+  - reveal.js

docs/.vale/asciidoctor/spelling-exceptions.txt

@@ -0,0 +1,33 @@
+Asciidoctor
+reveal.js
+Bundler
+gemset
+Gemfile
+npm
+JS
+js
+JavaScript
+Node
+toolchain
+Netlify
+Bilodeau
+Moulliard
+triaging
+prepending
+asciidoctor
+doctest
+html
+http
+Unversioned
+css
+docinfo
+Docinfo
+callout
+adoc
+https
+npx
+Dev
+prepended
+solarized
+preloading
+preprocessor

docs/antora.yml

@@ -9,10 +9,27 @@ nav:
 asciidoc:
   attributes:
     url-project-repo: 'https://github.com/asciidoctor/asciidoctor-reveal.js'
-    url-project-examples: 'https://github.com/asciidoctor/asciidoctor-reveal.js/blob/master/examples'
+    url-asciidoctorj-revealjs: 'https://github.com/asciidoctor/asciidoctorj-reveal.js'
+    url-project-examples: 'https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/examples'
+    url-project-templates: 'https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates'
     url-asciidoctor: 'https://github.com/asciidoctor/asciidoctor'
     url-asciidoctorjs: 'https://github.com/asciidoctor/asciidoctor.js'
     url-revealjs-home: 'https://revealjs.com'
     url-revealjs-gh: 'https://github.com/hakimel/reveal.js/blob/v3.9'
     url-revealjs-doc: 'https://github.com/hakimel/reveal.js/blob/v3.9/README.md'
-    url-nodejs-download: 'https://nodejs.org/en/download/'
+    url-nodejs-download: 'https://nodejs.org/en/download'
+    url-ruby-download: 'https://www.ruby-lang.org/en/downloads'
+    url-asciidoctor-abstractnode-attr: 'https://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr'
+    url-slim: 'http://slim-lang.com'
+    url-rouge: 'http://rouge.jneen.net'
+    url-pygment: 'https://pygments.org'
+    url-coderay: 'http://coderay.rubychan.de'
+    url-bundler: 'https://bundler.io'
+    url-highlightjs: 'https://highlightjs.org'
+    url-bulma: 'https://bulma.io'
+    url-gh-pages: 'https://pages.github.com'
+    url-netlify: 'https://www.netlify.com'
+    url-cdnjs: 'https://cdnjs.com'
+    url-gh-mogztter: 'https://github.com/Mogztter'
+    url-gh-mojavelinux: 'https://github.com/mojavelinux'
+    url-gh-graphitefriction: 'https://github.com/graphitefriction'

docs/modules/ROOT/pages/index.adoc

@@ -10,4 +10,4 @@ There are four main technology stacks that can convert AsciiDoc into HTML5 / rev
 * xref:setup:ruby-setup.adoc[Asciidoctor / Ruby / Bundler]
 * xref:setup:node-js-setup.adoc[Asciidoctor.js / JavaScript (Node.js) / npm]
 * xref:setup:standalone-executable.adoc[Standalone Executable]
-* https://github.com/asciidoctor/asciidoctorj-reveal.js[AsciidoctorJ / JVM / Maven^]
+* {url-asciidoctorj-revealjs}[AsciidoctorJ / JVM / Maven^]

docs/modules/ROOT/pages/showcase.adoc

@@ -4,7 +4,7 @@
 
 A smooth presentation, featuring video backgrounds, slide transitions, code and callout examples and the use of notes.
 
-https://bentolor.github.io/java9to13/[Presentation] and https://github.com/bentolor/java9to13[source]
+https://bentolor.github.io/java9to13/[Presentation^] and https://github.com/bentolor/java9to13[source^]
 
 === Screenshots
 

docs/modules/converter/pages/custom-styles.adoc

@@ -4,7 +4,7 @@
 == CSS Override
 
 If you use the `:customcss:` document attribute, a CSS file of the name given in the attribute is added to the list of CSS resources loaded by the rendered HTML.
-Doing so, you can then easily override specific elements of your theme per presentation.
+Doing so, you can then override specific elements of your theme per presentation.
 
 For example, to do proper position-independent text placement of a title slide with a specific background you can use:
 

docs/modules/converter/pages/docinfo.adoc

@@ -2,7 +2,7 @@
 :navtitle: Docinfo
 // Originally from https://github.com/asciidoctor/asciidoctor-bespoke#supplemental-content
 
-It's possible to inject supplemental content into the output document using http://asciidoctor.org/docs/user-manual/#docinfo-file[docinfo files].
+It's possible to inject supplemental content into the output document using xref:asciidoctor:docinfo.adoc[docinfo files].
 This core feature of AsciiDoc has been adapted to work with the reveal.js converter.
 
 Currently, there are three insertion locations for docinfo content in a reveal.js document:

docs/modules/converter/pages/features.adoc

@@ -54,7 +54,7 @@ See {url-project-repo}/blob/master/examples/concealed-slide-titles.adoc[conceale
 NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to.
 
 IMPORTANT: Like the first page of an AsciiDoc document, the first slide is handled differently.
-To hide the whole slide use the `:notitle:` http://asciidoctor.org/docs/user-manual/#header-summary[document attribute].
+To hide the whole slide use the `:notitle:` xref:asciidoc:document:header-ref.adoc[document attribute].
 To achieve the effect of hiding only the first slide's title, combine the `:notitle:` attribute on the first slide and use `[%notitle]` on the second slide which will, in effect, be your first slide now.
 
 == Content meant for multiple converters