chore: add linter for Markdown files (#1361)

Author: alexandear

.github/workflows/lint.yaml

@@ -32,8 +32,8 @@ jobs:
           find . -type f -name '*.go' -not -path './testdata/*' -exec gofmt -w {} +
           git diff --exit-code
 
-  lint:
-    name: Lint
+  lint-go:
+    name: Lint Go
     runs-on: ubuntu-latest
     steps:
 
@@ -55,3 +55,12 @@ jobs:
       uses: golangci/golangci-lint-action@v8
       with:
         version: v2.1.6
+
+  lint-md:
+    name: Lint Markdown
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v20
+        with:
+          config: .markdownlint-cli2.yaml

.markdownlint-cli2.yaml

@@ -0,0 +1,34 @@
+# A configuration file for markdownlint-cli2.
+
+# Fix any fixable errors
+fix: false
+
+# Rules description can be found at https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md
+config:
+  # Default state for all rules
+  default: true
+
+  # MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/md010.md
+  MD010:
+    code_blocks: false
+
+  # MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/md013.md
+  MD013:
+    line_length: 150
+    code_block_line_length: 200
+
+  # MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/md033.md
+  MD033: false
+
+  # MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/md055.md
+  MD055: false
+
+# Define glob expressions to use
+globs:
+  - "*.md"
+
+# Disable banner message on stdout
+noBanner: true
+
+# Show found files on stdout
+showFound: true

CODE_OF_CONDUCT.md

@@ -2,7 +2,9 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project
+and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression,
+level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
@@ -24,19 +26,29 @@ Examples of unacceptable behavior by participants include:
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate
+and fair corrective action in response to any instances of unacceptable behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues,
+and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors
+that they deem inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+Examples of representing a project or community include using an official project e-mail address, posting via an official social media account,
+or acting as an appointed representative at an online or offline event.
+Representation of a project may be further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at minko@gechev.io. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [minko@gechev.io](mailto:minko@gechev.io).
+The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined
+by other members of the project's leadership.
 
 ## Attribution
 

CONTRIBUTING.md

@@ -16,11 +16,14 @@ Prerequisites:
 
 ## Submitting a Pull Request
 
-All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. See our [developer guide](DEVELOPING.md) for instructions on building the project.
+All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose.
+See our [developer guide](DEVELOPING.md) for instructions on building the project.
 
-Pull requests (fixes, new features, tests) are a great way to contribute to the project and help us make it better. Ideally, try to keep your PRs as focused as possible and keep your commits atomic and readable.
+Pull requests (fixes, new features, tests) are a great way to contribute to the project and help us make it better.
+Ideally, try to keep your PRs as focused as possible and keep your commits atomic and readable.
 
-To avoid disappointment when working on a PR, please ask us first in case someone else is already working on a PR for a change you wished to make. It's always a good idea to file an issue before starting work on a PR unless it's for something minor (such as a typo fix).
+To avoid disappointment when working on a PR, please ask us first in case someone else is already working on a PR for a change you wished to make.
+It's always a good idea to file an issue before starting work on a PR unless it's for something minor (such as a typo fix).
 
 We greatly appreciate any attention to tests. These help us validate that new work continues to function as expected over time.
 

DEVELOPING.md

@@ -6,13 +6,15 @@ This document explains how to build, test, and develop features for revive.
 
 Clone the project:
 
-```
+```bash
 git clone git@github.com:mgechev/revive.git
 cd revive
 ```
+
 ## Build
 
 In order to build the project run:
+
 ```bash
 make build
 ```
@@ -33,14 +35,17 @@ This will output debug information to `stderr` and to the log file `revive.log`
 
 If you want to develop a new rule, follow as an example the already existing rules in the [rule package](https://github.com/mgechev/revive/tree/master/rule).
 
-Each rule needs to implement the `lint.Rule` interface: 
+Each rule needs to implement the `lint.Rule` interface:
+
 ```go
 type Rule interface {
 	Name() string
 	Apply(*File, Arguments) []Failure
 }
 ```
+
 All rules with a configuration must implement `lint.ConfigurableRule` interface:
+
 ```go
 type ConfigurableRule interface {
 	Configure(Arguments) error
@@ -49,9 +54,10 @@ type ConfigurableRule interface {
 
 The `Arguments` type is an alias of the type `[]any`. The arguments of the rule are passed from the configuration file.
 
-#### Example
+### Example
 
-Let's suppose we have developed a rule called `BanStructNameRule` which disallow us to name a structure with a given identifier. We can set the banned identifier by using the TOML configuration file:
+Let's suppose we have developed a rule called `BanStructNameRule` which disallow us to name a structure with a given identifier.
+We can set the banned identifier by using the TOML configuration file:
 
 ```toml
 [rule.ban-struct-name]
@@ -61,10 +67,10 @@ Let's suppose we have developed a rule called `BanStructNameRule` which disallow
 With the snippet above we:
 
 - Enable the rule with the name `ban-struct-name`. The `Name()` method of our rule should return a string that matches `ban-struct-name`.
-- Configure the rule with the argument `Foo`. The list of arguments will be passed to `Apply(*File, Arguments)` together with the target file we're linting currently.
-
-A sample rule implementation can be found [here](/rule/argument_limit.go).
+- Configure the rule with the argument `Foo`.
+The list of arguments will be passed to `Apply(*File, Arguments)` together with the target file we're linting currently.
 
+A sample rule implementation can be [found here](/rule/argument_limit.go).
 
 ## Development of formatters
 
@@ -78,3 +84,27 @@ type Formatter interface {
 	Name() string
 }
 ```
+
+## Lint
+
+### Lint Markdown files
+
+We are using [markdownlint](https://github.com/DavidAnson/markdownlint) for checking Markdown files.
+
+1. Install [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2#install).
+2. Run the following command:
+
+```sh
+$ markdownlint-cli2 .
+Finding: *.{md,markdown} *.md
+Found:
+ CODE_OF_CONDUCT.md
+ CONTRIBUTING.md
+ DEVELOPING.md
+ README.md
+ RULES_DESCRIPTIONS.md
+Linting: 5 file(s)
+Summary: 0 error(s)
+```
+
+The tool automatically uses the config file [.markdownlint-cli2.yaml](./.markdownlint-cli2.yaml).