Skip to content

Commit 0e76b4d

Browse files
authored
docs: update TOC; check for TOC consistency in GHA (#1493)
1 parent e1d05f7 commit 0e76b4d

File tree

4 files changed

+181
-153
lines changed

4 files changed

+181
-153
lines changed

.github/workflows/lint.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,11 +72,24 @@ jobs:
7272
# https://taplo.tamasfe.dev/cli/installation/binary.html
7373
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
7474

75+
- name: Set up Node.js
76+
uses: actions/setup-node@v4
77+
with:
78+
node-version: '20'
79+
80+
- name: Install markdown-toc
81+
run: npm install -g markdown-toc
82+
7583
- name: Verify files format using markdownlint-cli2
7684
uses: DavidAnson/markdownlint-cli2-action@v20
7785
with:
7886
config: .markdownlint-cli2.yaml
7987

88+
- name: Verify TOC in markdown files
89+
run: |
90+
markdown-toc --maxdepth 4 --no-first1 --bullets "-" -i README.md && git diff --exit-code README.md
91+
markdown-toc --maxdepth 2 --no-first1 --bullets "-" -i RULES_DESCRIPTIONS.md && git diff --exit-code RULES_DESCRIPTIONS.md
92+
8093
- name: Verify code snippets using mdsf
8194
id: verify_snippets
8295
run: mdsf verify --on-missing-language-definition ignore --on-missing-tool-binary fail-fast .

DEVELOPING.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -93,15 +93,20 @@ type Formatter interface {
9393

9494
### Lint Markdown files
9595

96-
We use [markdownlint](https://github.com/DavidAnson/markdownlint) and [mdsf](https://github.com/hougesen/mdsf) to check Markdown files.
97-
`markdownlint` verifies document formatting, such as line length and empty lines, while `mdsf` is responsible for formatting code snippets.
96+
We use [markdownlint](https://github.com/DavidAnson/markdownlint),
97+
[markdown-toc](https://github.com/jonschlinkert/markdown-toc),
98+
and [mdsf](https://github.com/hougesen/mdsf) to check Markdown files.
99+
`markdownlint` verifies document formatting, such as line length and empty lines.
100+
`markdown-toc` checks the entries in the table of contents.
101+
`mdsf` is responsible for formatting code snippets.
98102

99103
1. Install [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2#install).
100-
2. Install [mdsf](https://mdsf.mhouge.dk/#installation) and formatters:
104+
2. Install [markdown-toc](https://github.com/jonschlinkert/markdown-toc#quick-start).
105+
3. Install [mdsf](https://mdsf.mhouge.dk/#installation) and formatters:
101106
- [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) for `go`: `go install golang.org/x/tools/cmd/goimports@latest`
102107
- [shfmt](https://github.com/mvdan/sh#shfmt) for `sh, shell, bash`: `go install mvdan.cc/sh/v3/cmd/shfmt@latest`
103108
- [taplo](https://taplo.tamasfe.dev/cli/installation/binary.html) for `toml`
104-
3. Run the following command to check formatting:
109+
4. Run the following command to check formatting:
105110

106111
```shellsession
107112
$ markdownlint-cli2 .
@@ -118,7 +123,15 @@ Summary: 0 error(s)
118123

119124
_The `markdownlint-cli2` tool automatically uses the config file [.markdownlint-cli2.yaml](./.markdownlint-cli2.yaml)._
120125
\
121-
4. Run the following commands to verify and format code snippets:
126+
4. Run the following command to check TOC:
127+
128+
```sh
129+
markdown-toc --maxdepth 4 --no-first1 --bullets "-" -i README.md && git diff --exit-code README.md
130+
markdown-toc --maxdepth 2 --no-first1 --bullets "-" -i RULES_DESCRIPTIONS.md && git diff --exit-code RULES_DESCRIPTIONS.md
131+
```
132+
133+
\
134+
5. Run the following commands to verify and format code snippets:
122135

123136
```sh
124137
mdsf verify .

README.md

Lines changed: 50 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -32,57 +32,56 @@ If you disable them in the config file, revive will run over 6x faster than goli
3232
<img src="./assets/demo.svg" alt="" width="700">
3333
</p>
3434

35-
<!-- TOC -->
36-
37-
- [revive](#revive)
38-
- [Installation](#installation)
39-
- [Homebrew](#homebrew)
40-
- [Install from Sources](#install-from-sources)
41-
- [Docker](#docker)
42-
- [Manual Binary Download](#manual-binary-download)
43-
- [Usage](#usage)
44-
- [Bazel](#bazel)
45-
- [Text Editors](#text-editors)
46-
- [GitHub Actions](#github-actions)
47-
- [Continuous Integration](#continuous-integration)
48-
- [Linter aggregators](#linter-aggregators)
49-
- [golangci-lint](#golangci-lint)
50-
- [Command Line Flags](#command-line-flags)
51-
- [Sample Invocations](#sample-invocations)
52-
- [Comment Directives](#comment-directives)
53-
- [Configuration](#configuration)
54-
- [Default Configuration](#default-configuration)
55-
- [Custom Configuration](#custom-configuration)
56-
- [Recommended Configuration](#recommended-configuration)
57-
- [Rule-level file excludes](#rule-level-file-excludes)
58-
- [Available Rules](#available-rules)
59-
- [Configurable rules](#configurable-rules)
60-
- [`var-naming`](#var-naming)
61-
- [Available Formatters](#available-formatters)
62-
- [Friendly](#friendly)
63-
- [Stylish](#stylish)
64-
- [Default](#default)
65-
- [Plain](#plain)
66-
- [Unix](#unix)
67-
- [JSON](#json)
68-
- [NDJSON](#ndjson)
69-
- [Checkstyle](#checkstyle)
70-
- [SARIF](#sarif)
71-
- [Extensibility](#extensibility)
72-
- [Writing a Custom Rule](#writing-a-custom-rule)
73-
- [Using `revive` as a library](#using-revive-as-a-library)
74-
- [Custom Formatter](#custom-formatter)
75-
- [Speed Comparison](#speed-comparison)
76-
- [golint](#golint)
77-
- [revive's speed](#revives-speed)
78-
- [Overriding colorization detection](#overriding-colorization-detection)
79-
- [Who uses Revive](#who-uses-revive)
80-
- [Contributors](#contributors)
81-
- [Maintainers](#maintainers)
82-
- [All](#all)
83-
- [License](#license)
84-
85-
<!-- /TOC -->
35+
<!-- toc -->
36+
37+
- [Installation](#installation)
38+
- [Homebrew](#homebrew)
39+
- [Install from Sources](#install-from-sources)
40+
- [Docker](#docker)
41+
- [Manual Binary Download](#manual-binary-download)
42+
- [Usage](#usage)
43+
- [Bazel](#bazel)
44+
- [Text Editors](#text-editors)
45+
- [GitHub Actions](#github-actions)
46+
- [Continuous Integration](#continuous-integration)
47+
- [Linter aggregators](#linter-aggregators)
48+
- [golangci-lint](#golangci-lint)
49+
- [Command Line Flags](#command-line-flags)
50+
- [Sample Invocations](#sample-invocations)
51+
- [Comment Directives](#comment-directives)
52+
- [Configuration](#configuration)
53+
- [Default Configuration](#default-configuration)
54+
- [Custom Configuration](#custom-configuration)
55+
- [Recommended Configuration](#recommended-configuration)
56+
- [Rule-level file excludes](#rule-level-file-excludes)
57+
- [Available Rules](#available-rules)
58+
- [Configurable rules](#configurable-rules)
59+
- [`var-naming`](#var-naming)
60+
- [Available Formatters](#available-formatters)
61+
- [Friendly](#friendly)
62+
- [Stylish](#stylish)
63+
- [Default](#default)
64+
- [Plain](#plain)
65+
- [Unix](#unix)
66+
- [JSON](#json)
67+
- [NDJSON](#ndjson)
68+
- [Checkstyle](#checkstyle)
69+
- [SARIF](#sarif)
70+
- [Extensibility](#extensibility)
71+
- [Writing a Custom Rule](#writing-a-custom-rule)
72+
- [Using `revive` as a library](#using-revive-as-a-library)
73+
- [Custom Formatter](#custom-formatter)
74+
- [Speed Comparison](#speed-comparison)
75+
- [golint](#golint)
76+
- [revive's speed](#revives-speed)
77+
- [Overriding colorization detection](#overriding-colorization-detection)
78+
- [Who uses Revive](#who-uses-revive)
79+
- [Contributors](#contributors)
80+
- [Maintainers](#maintainers)
81+
- [All](#all)
82+
- [License](#license)
83+
84+
<!-- tocstop -->
8685

8786
## Installation
8887

RULES_DESCRIPTIONS.md

Lines changed: 100 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -2,103 +2,106 @@
22

33
List of all available rules.
44

5-
- [Description of available rules](#description-of-available-rules)
6-
- [add-constant](#add-constant)
7-
- [argument-limit](#argument-limit)
8-
- [atomic](#atomic)
9-
- [banned-characters](#banned-characters)
10-
- [bare-return](#bare-return)
11-
- [blank-imports](#blank-imports)
12-
- [bool-literal-in-expr](#bool-literal-in-expr)
13-
- [call-to-gc](#call-to-gc)
14-
- [cognitive-complexity](#cognitive-complexity)
15-
- [comment-spacings](#comment-spacings)
16-
- [comments-density](#comments-density)
17-
- [confusing-naming](#confusing-naming)
18-
- [confusing-results](#confusing-results)
19-
- [constant-logical-expr](#constant-logical-expr)
20-
- [context-as-argument](#context-as-argument)
21-
- [context-keys-type](#context-keys-type)
22-
- [cyclomatic](#cyclomatic)
23-
- [datarace](#datarace)
24-
- [deep-exit](#deep-exit)
25-
- [defer](#defer)
26-
- [dot-imports](#dot-imports)
27-
- [duplicated-imports](#duplicated-imports)
28-
- [early-return](#early-return)
29-
- [empty-block](#empty-block)
30-
- [empty-lines](#empty-lines)
31-
- [enforce-map-style](#enforce-map-style)
32-
- [enforce-repeated-arg-type-style](#enforce-repeated-arg-type-style)
33-
- [enforce-slice-style](#enforce-slice-style)
34-
- [enforce-switch-style](#enforce-switch-style)
35-
- [error-naming](#error-naming)
36-
- [error-return](#error-return)
37-
- [error-strings](#error-strings)
38-
- [errorf](#errorf)
39-
- [exported](#exported)
40-
- [file-header](#file-header)
41-
- [file-length-limit](#file-length-limit)
42-
- [filename-format](#filename-format)
43-
- [flag-parameter](#flag-parameter)
44-
- [function-length](#function-length)
45-
- [function-result-limit](#function-result-limit)
46-
- [get-return](#get-return)
47-
- [identical-branches](#identical-branches)
48-
- [identical-ifelseif-branches](#identical-ifelseif-branches)
49-
- [identical-ifelseif-conditions](#identical-ifelseif-conditions)
50-
- [identical-switch-branches](#identical-switch-branches)
51-
- [identical-switch-conditions](#identical-switch-conditions)
52-
- [if-return](#if-return)
53-
- [import-alias-naming](#import-alias-naming)
54-
- [import-shadowing](#import-shadowing)
55-
- [imports-blocklist](#imports-blocklist)
56-
- [increment-decrement](#increment-decrement)
57-
- [indent-error-flow](#indent-error-flow)
58-
- [line-length-limit](#line-length-limit)
59-
- [max-control-nesting](#max-control-nesting)
60-
- [max-public-structs](#max-public-structs)
61-
- [modifies-parameter](#modifies-parameter)
62-
- [modifies-value-receiver](#modifies-value-receiver)
63-
- [nested-structs](#nested-structs)
64-
- [optimize-operands-order](#optimize-operands-order)
65-
- [package-comments](#package-comments)
66-
- [package-directory-mismatch](#package-directory-mismatch)
67-
- [range-val-address](#range-val-address)
68-
- [range-val-in-closure](#range-val-in-closure)
69-
- [range](#range)
70-
- [receiver-naming](#receiver-naming)
71-
- [redefines-builtin-id](#redefines-builtin-id)
72-
- [redundant-build-tag](#redundant-build-tag)
73-
- [redundant-import-alias](#redundant-import-alias)
74-
- [redundant-test-main-exit](#redundant-test-main-exit)
75-
- [string-format](#string-format)
76-
- [string-of-int](#string-of-int)
77-
- [struct-tag](#struct-tag)
78-
- [superfluous-else](#superfluous-else)
79-
- [time-date](#time-date)
80-
- [time-equal](#time-equal)
81-
- [time-naming](#time-naming)
82-
- [unchecked-type-assertion](#unchecked-type-assertion)
83-
- [unconditional-recursion](#unconditional-recursion)
84-
- [unexported-naming](#unexported-naming)
85-
- [unexported-return](#unexported-return)
86-
- [unhandled-error](#unhandled-error)
87-
- [unnecessary-format](#unnecessary-format)
88-
- [unnecessary-stmt](#unnecessary-stmt)
89-
- [unreachable-code](#unreachable-code)
90-
- [unsecure-url-scheme](#unsecure-url-scheme)
91-
- [unused-parameter](#unused-parameter)
92-
- [unused-receiver](#unused-receiver)
93-
- [use-any](#use-any)
94-
- [use-errors-new](#use-errors-new)
95-
- [use-fmt-print](#use-fmt-print)
96-
- [use-waitgroup-go](#use-waitgroup-go)
97-
- [useless-break](#useless-break)
98-
- [useless-fallthrough](#useless-fallthrough)
99-
- [var-declaration](#var-declaration)
100-
- [var-naming](#var-naming)
101-
- [waitgroup-by-value](#waitgroup-by-value)
5+
<!-- toc -->
6+
7+
- [add-constant](#add-constant)
8+
- [argument-limit](#argument-limit)
9+
- [atomic](#atomic)
10+
- [banned-characters](#banned-characters)
11+
- [bare-return](#bare-return)
12+
- [blank-imports](#blank-imports)
13+
- [bool-literal-in-expr](#bool-literal-in-expr)
14+
- [call-to-gc](#call-to-gc)
15+
- [cognitive-complexity](#cognitive-complexity)
16+
- [comment-spacings](#comment-spacings)
17+
- [comments-density](#comments-density)
18+
- [confusing-naming](#confusing-naming)
19+
- [confusing-results](#confusing-results)
20+
- [constant-logical-expr](#constant-logical-expr)
21+
- [context-as-argument](#context-as-argument)
22+
- [context-keys-type](#context-keys-type)
23+
- [cyclomatic](#cyclomatic)
24+
- [datarace](#datarace)
25+
- [deep-exit](#deep-exit)
26+
- [defer](#defer)
27+
- [dot-imports](#dot-imports)
28+
- [duplicated-imports](#duplicated-imports)
29+
- [early-return](#early-return)
30+
- [empty-block](#empty-block)
31+
- [empty-lines](#empty-lines)
32+
- [enforce-map-style](#enforce-map-style)
33+
- [enforce-repeated-arg-type-style](#enforce-repeated-arg-type-style)
34+
- [enforce-slice-style](#enforce-slice-style)
35+
- [enforce-switch-style](#enforce-switch-style)
36+
- [error-naming](#error-naming)
37+
- [error-return](#error-return)
38+
- [error-strings](#error-strings)
39+
- [errorf](#errorf)
40+
- [exported](#exported)
41+
- [file-header](#file-header)
42+
- [file-length-limit](#file-length-limit)
43+
- [filename-format](#filename-format)
44+
- [flag-parameter](#flag-parameter)
45+
- [function-length](#function-length)
46+
- [function-result-limit](#function-result-limit)
47+
- [get-return](#get-return)
48+
- [identical-branches](#identical-branches)
49+
- [identical-ifelseif-branches](#identical-ifelseif-branches)
50+
- [identical-ifelseif-conditions](#identical-ifelseif-conditions)
51+
- [identical-switch-branches](#identical-switch-branches)
52+
- [identical-switch-conditions](#identical-switch-conditions)
53+
- [if-return](#if-return)
54+
- [import-alias-naming](#import-alias-naming)
55+
- [import-shadowing](#import-shadowing)
56+
- [imports-blocklist](#imports-blocklist)
57+
- [increment-decrement](#increment-decrement)
58+
- [indent-error-flow](#indent-error-flow)
59+
- [line-length-limit](#line-length-limit)
60+
- [max-control-nesting](#max-control-nesting)
61+
- [max-public-structs](#max-public-structs)
62+
- [modifies-parameter](#modifies-parameter)
63+
- [modifies-value-receiver](#modifies-value-receiver)
64+
- [nested-structs](#nested-structs)
65+
- [optimize-operands-order](#optimize-operands-order)
66+
- [package-comments](#package-comments)
67+
- [package-directory-mismatch](#package-directory-mismatch)
68+
- [range-val-address](#range-val-address)
69+
- [range-val-in-closure](#range-val-in-closure)
70+
- [range](#range)
71+
- [receiver-naming](#receiver-naming)
72+
- [redefines-builtin-id](#redefines-builtin-id)
73+
- [redundant-build-tag](#redundant-build-tag)
74+
- [redundant-import-alias](#redundant-import-alias)
75+
- [redundant-test-main-exit](#redundant-test-main-exit)
76+
- [string-format](#string-format)
77+
- [string-of-int](#string-of-int)
78+
- [struct-tag](#struct-tag)
79+
- [superfluous-else](#superfluous-else)
80+
- [time-date](#time-date)
81+
- [time-equal](#time-equal)
82+
- [time-naming](#time-naming)
83+
- [unchecked-type-assertion](#unchecked-type-assertion)
84+
- [unconditional-recursion](#unconditional-recursion)
85+
- [unexported-naming](#unexported-naming)
86+
- [unexported-return](#unexported-return)
87+
- [unhandled-error](#unhandled-error)
88+
- [unnecessary-format](#unnecessary-format)
89+
- [unnecessary-stmt](#unnecessary-stmt)
90+
- [unreachable-code](#unreachable-code)
91+
- [unsecure-url-scheme](#unsecure-url-scheme)
92+
- [unused-parameter](#unused-parameter)
93+
- [unused-receiver](#unused-receiver)
94+
- [use-any](#use-any)
95+
- [use-errors-new](#use-errors-new)
96+
- [use-fmt-print](#use-fmt-print)
97+
- [use-waitgroup-go](#use-waitgroup-go)
98+
- [useless-break](#useless-break)
99+
- [useless-fallthrough](#useless-fallthrough)
100+
- [var-declaration](#var-declaration)
101+
- [var-naming](#var-naming)
102+
- [waitgroup-by-value](#waitgroup-by-value)
103+
104+
<!-- tocstop -->
102105

103106
## add-constant
104107

0 commit comments

Comments
 (0)