docs: update TOC; check for TOC consistency in GHA (#1493)

.github/workflows/lint.yaml

@@ -72,11 +72,24 @@ jobs:
         # https://taplo.tamasfe.dev/cli/installation/binary.html
         run: curl -fsSL https://github.com/tamasfe/taplo/releases/download/0.10.0/taplo-linux-x86_64.gz | gzip -d - | install -m 755 /dev/stdin /usr/local/bin/taplo
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install markdown-toc
+        run: npm install -g markdown-toc
+
       - name: Verify files format using markdownlint-cli2
         uses: DavidAnson/markdownlint-cli2-action@v20
         with:
           config: .markdownlint-cli2.yaml
 
+      - name: Verify TOC in markdown files
+        run: |
+          markdown-toc --maxdepth 4 --no-first1 --bullets "-" -i README.md && git diff --exit-code README.md
+          markdown-toc --maxdepth 2 --no-first1 --bullets "-" -i RULES_DESCRIPTIONS.md && git diff --exit-code RULES_DESCRIPTIONS.md
+
       - name: Verify code snippets using mdsf
         id: verify_snippets
         run: mdsf verify --on-missing-language-definition ignore --on-missing-tool-binary fail-fast .

DEVELOPING.md

@@ -93,15 +93,20 @@ type Formatter interface {
 
 ### Lint Markdown files
 
-We use [markdownlint](https://github.com/DavidAnson/markdownlint) and [mdsf](https://github.com/hougesen/mdsf) to check Markdown files.
-`markdownlint` verifies document formatting, such as line length and empty lines, while `mdsf` is responsible for formatting code snippets.
+We use [markdownlint](https://github.com/DavidAnson/markdownlint),
+[markdown-toc](https://github.com/jonschlinkert/markdown-toc),
+and [mdsf](https://github.com/hougesen/mdsf) to check Markdown files.
+`markdownlint` verifies document formatting, such as line length and empty lines.
+`markdown-toc` checks the entries in the table of contents.
+`mdsf` is responsible for formatting code snippets.
 
 1. Install [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2#install).
-2. Install [mdsf](https://mdsf.mhouge.dk/#installation) and formatters:
+2. Install [markdown-toc](https://github.com/jonschlinkert/markdown-toc#quick-start).
+3. Install [mdsf](https://mdsf.mhouge.dk/#installation) and formatters:
     - [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) for `go`: `go install golang.org/x/tools/cmd/goimports@latest`
     - [shfmt](https://github.com/mvdan/sh#shfmt) for `sh, shell, bash`: `go install mvdan.cc/sh/v3/cmd/shfmt@latest`
     - [taplo](https://taplo.tamasfe.dev/cli/installation/binary.html) for `toml`
-3. Run the following command to check formatting:
+4. Run the following command to check formatting:
 
 ```shellsession
 $ markdownlint-cli2 .
@@ -118,7 +123,15 @@ Summary: 0 error(s)
 
 _The `markdownlint-cli2` tool automatically uses the config file [.markdownlint-cli2.yaml](./.markdownlint-cli2.yaml)._
 \
-4. Run the following commands to verify and format code snippets:
+4. Run the following command to check TOC:
+
+```sh
+markdown-toc --maxdepth 4 --no-first1 --bullets "-" -i README.md && git diff --exit-code README.md
+markdown-toc --maxdepth 2 --no-first1 --bullets "-" -i RULES_DESCRIPTIONS.md && git diff --exit-code RULES_DESCRIPTIONS.md
+```
+
+\
+5. Run the following commands to verify and format code snippets:
 
 ```sh
 mdsf verify .

README.md

@@ -32,9 +32,8 @@ If you disable them in the config file, revive will run over 6x faster than goli
   <img src="./assets/demo.svg" alt="" width="700">
 </p>
 
-<!-- TOC -->
+<!-- toc -->
 
-- [revive](#revive)
 - [Installation](#installation)
   - [Homebrew](#homebrew)
   - [Install from Sources](#install-from-sources)
@@ -82,7 +81,7 @@ If you disable them in the config file, revive will run over 6x faster than goli
   - [All](#all)
 - [License](#license)
 
-<!-- /TOC -->
+<!-- tocstop -->
 
 ## Installation
 

RULES_DESCRIPTIONS.md

@@ -2,7 +2,8 @@
 
 List of all available rules.
 
-- [Description of available rules](#description-of-available-rules)
+<!-- toc -->
+
 - [add-constant](#add-constant)
 - [argument-limit](#argument-limit)
 - [atomic](#atomic)
@@ -100,6 +101,8 @@ List of all available rules.
 - [var-naming](#var-naming)
 - [waitgroup-by-value](#waitgroup-by-value)
 
+<!-- tocstop -->
+
 ## add-constant
 
 _Description_: Suggests using constant for [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants)