Style checking with Vale

.github/workflows/tests.yml

@@ -28,6 +28,11 @@ jobs:
         with:
           node-version: 18
       - run: npm ci
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: docs
+          reporter: github-pr-review
+          filter_mode: added
       - run: npm run test -- --reporter JSON --reporter-option output=mocha.json --filesToCheck=${{ needs.checkChangedFiles.outputs.files }}
         continue-on-error: true
       - run: ls

.gitignore

@@ -6,5 +6,10 @@ node_modules
 out
 build
 
-filesToTest.txt
+# Vale
+test/styles/*
+!test/styles/Vocab/
+!test/styles/Tezos/
 
+test/styles/Vocab/*
+!test/styles/Vocab/Tezos

.vale.ini

@@ -0,0 +1,14 @@
+# https://vale.sh/docs/topics/config/
+
+StylesPath = test/styles
+
+MinAlertLevel = suggestion
+
+Vocab = Tezos
+
+# Treat mdx files as md files
+[formats]
+mdx = md
+
+[*.{md,mdx}]
+BasedOnStyles = Vale, Tezos

README.md

@@ -40,7 +40,13 @@ Finally, open [http://localhost:3000](http://localhost:3000) in your browser to
 ## Tests
 
 The workflow `.github/workflows/tests.yml` runs automated tests on pull requests.
-To run tests locally, run `npm run test -- --filesToCheck=docs/developing.md,docs/architecture.mdx`, where `--filesToCheck` is a comma-separated list of the MD and MDX files to test.
+It includes these tests:
+
+- Mocha tests that check for broken links to images.
+To run these tests locally, run `npm run test -- --filesToCheck=docs/developing.md,docs/architecture.mdx`, where `--filesToCheck` is a comma-separated list of the MD and MDX files to test.
+
+- Vale tests for style, spelling, and capitalization.
+To run these tests locally, install [Vale](https://vale.sh/) and run `npm run vale`.
 
 Docusaurus automatically checks for broken links and markdown-encoded images when you run `npm run build`.
 

package.json

@@ -10,6 +10,7 @@
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
+    "vale": "vale sync && vale docs/",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "test": "mocha",

test/styles/Tezos/Capitalize.yml

@@ -0,0 +1,7 @@
+extends: substitution
+message: "Always capitalize '%s'"
+level: error
+ignorecase: true
+swap:
+  smart rollup: Smart Rollup
+  smart rollups: Smart Rollups

test/styles/Tezos/DoNotCapitalize.yml

@@ -0,0 +1,7 @@
+extends: substitution
+message: "Do not capitalize '%s'"
+level: error
+swap:
+  '(?!^)Smart Contracts?': 'smart contract'
+  '(?!^)Smart contracts?': 'smart contract'
+  'smart Contracts?': 'smart contract'

test/styles/Tezos/Substitutions.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: Use '%s' instead of '%s'
+level: warning
+ignorecase: true
+# swap maps tokens in form of bad: good
+swap:
+  l1: layer 1
+  l2: layer 2

test/styles/Tezos/Terms.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Do not use the term '%s'"
+level: error
+ignorecase: true
+tokens:
+   - 'official Tezos'
+   - 'official tezos'
+   - 'ICO'
+   - 'investors?'
+   - 'initial coin offering'
+   - 'chapter'
+   - 'article'

test/styles/Vocab/Tezos/accept.txt

@@ -0,0 +1,45 @@
+Airgap
+API
+big_map
+blockchain
+CameLIGO
+Carthagenet
+cryptocurrency
+Completium
+dApps?
+delegator
+deserializ(ed)?
+Dailynet
+Flextesa
+Ghostnet
+JsLIGO
+Kukai
+LIGO
+Mainnet
+Merkle
+Mumbainet
+NFT
+OCaml
+off-chain
+on-chain
+Oxhead
+Oxhead Alpha
+Rollups?
+Sapling
+SDKs?
+stablecoin
+supermajority
+syntax(es)?
+Taquito
+Taqueria
+testnet
+tez
+Tezos
+[Tt]zStats
+Umami
+URIs?
+validator
+Vite
+VSCode
+Vue
+Breitman

test/styles/Vocab/Tezos/reject.txt

@@ -0,0 +1 @@
+crypto