Investigate about linter for Asciidoc syntax

[uguy]

Using a linter could be usefull for contributor in making clean pull request.

An issue exist on this topic: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/6

They are mentioning a tool named vale that may be useful as a start. (see https://docs.errata.ai/vale/scoping#asciidoc)

[alachambre]

https://www.npmjs.com/package/textlint-plugin-asciidoctor

didn't test

[jeromecambon]

I tested Vale, which is NOT an Asciidoc syntax linter, but a check of the syntax style. One may define a set of rules to check, with different severities. A set of pre-defined set of rules can be used : Google, proselint, write-good, ... An example using these rules, on the Bonita page "Data Management in the UI Designer":

It is possible also to add words to a dictionary, to avoid warnings on well-known Bonita words.

I have tried this on a set of Bonita doc pages, and it gives good suggestions and errors (especially for typos). I used the follwing setting in my .vale.ini file:

MinAlertLevel = suggestion
Vocab = Base

Packages = Google, proselint, write-good, alex, Joblint

[*]
BasedOnStyles = Vale, Google, proselint, write-good, alex, Joblint

So we could use it using the github action: https://github.com/marketplace/actions/vale-linter, in contribution-check workflow for instance.

[jeromecambon]

I also tried textlint-plugin-asciidoctor, but didn't succeed to make it work. Anyway seems a very limited package, with very few support.

[jeromecambon]

We decided to test it for a while to check if it is useful: add the suggestions as a comment in the PR (single comment, use e.g. https://github.com/marketplace/actions/sticky-pull-request-comment)

[jeromecambon]

The Vale github action provides a smart reporter in the "Check" PR section, as well as in the "Files changed":

https://user-images.githubusercontent.com/17833345/195867268-50570f96-b5ee-4787-a598-215b9f26b99d.mov