chore: improve markdownlint (#946)

Co-authored-by: Meg McRoberts <mmcroberts@cloudbees.com>
Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>

docs/markdownlint-rules.yaml → .markdownlint.yaml

@@ -2,3 +2,7 @@ line-length:
   line_length: 120
   tables: false
   code_blocks: false
+no-inline-html:
+  allowed_elements:
+    - details
+    - summary

.markdownlintignore

@@ -0,0 +1 @@
+CHANGELOG.md

CONTRIBUTING.md

@@ -99,10 +99,12 @@ This project uses a set of linters to ensure good code quality.
 In order to make proper use of those linters inside an IDE,
 the following configuration is required.
 
+### Golangci-lint
+
 Further information can also be found in
 the [`golangci-lint` documentation](https://golangci-lint.run/usage/integrations/).
 
-### Visual Studio Code
+#### Visual Studio Code
 
 In Visual Studio Code the
 [Golang](https://marketplace.visualstudio.com/items?itemName=aldijav.golangwithdidi)
@@ -132,7 +134,7 @@ configuration file enables all linters used in this project.
 },
 ```
 
-### GoLand / IntelliJ requirements
+#### GoLand / IntelliJ requirements
 
 * Install either the **GoLand** or **IntelliJ**  Integrated Development Environment
 (IDE) for the Go programming language, plus the [Go Linter](https://plugins.jetbrains.com/plugin/12496-go-linter) plugin.
@@ -151,6 +153,42 @@ If you are on Windows, you need to install **make** for the above process to com
 When using the make command on Windows, you may receive an `unrecognized command` error for a command that is installed.
 This usually indicates that `PATH` for the binary is not set correctly).
 
+### Markdownlint
+
+We are using [markdownlint](https://github.com/DavidAnson/markdownlint) to ensure consistent styling
+within our Markdown files.
+Specifically we are using [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli).
+
+We are using `GNU MAKE` to ensure the same functionality locally and within our CI builds.
+This should allow easier debugging and problem resolution.
+
+#### Markdownlint execution
+
+To verify that your markdown code conforms to the rules, run the following on your local branch:
+
+```shell
+make markdownlint
+```
+
+To use the auto-fix option, run:
+
+```shell
+make markdownlint-fix
+```
+
+#### Markdownlint Configuration
+
+We use the default configuration values for `markdownlint`.
+
+This means:
+
+* [.markdownlint.yaml](./.markdownlint.yaml) contains the rule configuration
+* [.markdownlintignore](./.markdownlintignore) list files that markdown-lint ignores,  using `.gitignore` conventions
+
+We use the default values, so tools like
+[markdownlint for VSCode](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+can be used without additional configuration.
+
 ## Submit a Pull Request 🚀
 
 At this point, you should switch back to the `main` branch in your repository,
@@ -194,6 +232,7 @@ feat(api): New endpoint for feature X (#1234)
 
 If you have **breaking changes** in your PR, it is important to note them in the PR
 description but also in the merge commit for that PR.
+
 When pressing "squash and merge", you have the option to fill out the commit message.
 Please use that feature to add the breaking changes according to the
 [conventional commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/).
@@ -284,18 +323,3 @@ by creating a pre-commit git hook as follows:
     ```bash
     chmod +x ./.git/hooks/prepare-commit-msg
     ```
-
-### Markdown linting
-
-To check your markdown files for linter errors, run the following
-from the repo root:
-
-```shell
-make markdownlint
-```
-
-To use the auto-fix option, run:
-
-```shell
-make markdownlint-fix
-```

Makefile

@@ -110,10 +110,5 @@ build-deploy-certmanager:
 .PHONY: build-deploy-dev-environment
 build-deploy-dev-environment: build-deploy-certmanager build-deploy-operator build-deploy-metrics-operator build-deploy-scheduler
 
-markdownlint:
-	docker run -v $(CURDIR):/workdir --rm  ghcr.io/igorshubovych/markdownlint-cli:latest  "**/*.md" --config "/workdir/docs/markdownlint-rules.yaml" --ignore "/workdir/CHANGELOG.md"
-
-markdownlint-fix:
-	docker run -v $(CURDIR):/workdir --rm  ghcr.io/igorshubovych/markdownlint-cli:latest  "**/*.md" --config "/workdir/docs/markdownlint-rules.yaml" --fix --ignore "/workdir/CHANGELOG.md"
 
 include docs/Makefile

docs/Makefile

@@ -6,7 +6,7 @@ IMAGE := klakegg/hugo:$(HUGO_VERSION)
 PORT := 1314
 DOCKER_CMD := docker run --rm -t -e HUGO_CACHEDIR=/src/tmp/.hugo
 
-.PHONY: build server clean shell htmltest
+.PHONY: build server clean shell
 
 build:
 	$(DOCKER_CMD) $(VOLUMES) $(IMAGE) -D -v
@@ -20,5 +20,29 @@ server:
 clean:
 	$(DOCKER_CMD) $(VOLUMES) $(IMAGE) --cleanDestinationDir
 
+.PHONY: htmltest
+
+# renovate: datasource=docker depName=wjdp/htmltest
+HTMLTEST_VERSION := v0.17.0
 htmltest: build
-	$(DOCKER_CMD) -v $(ROOT_DIR):/test wjdp/htmltest -c .htmltest.yml public
+	$(DOCKER_CMD) -v $(ROOT_DIR):/test wjdp/htmltest:$(HTMLTEST_VERSION) -c .htmltest.yml public
+
+.PHONY: lint lint-fix
+lint: markdownlint
+lint: lint-fix
+
+# Markdown lint configuration
+#
+# - .markdownlintignore holds the configuration for files to be ignored
+# - .markdownlint.yaml contains the rules for markdownfiles
+#
+# renovate: datasource=docker depName=ghcr.io/igorshubovych/markdownlint-cli
+MDL_DOCKER_VERSION := v0.33.0
+MDL_CMD := docker run -v $(ROOT_DIR)../:/workdir --rm  ghcr.io/igorshubovych/markdownlint-cli:$(MDL_DOCKER_VERSION)  "**/*.md" 
+
+.PHONY: markdownlint markdownlint-fix
+markdownlint:
+	$(MDL_CMD)
+
+markdownlint-fix:
+	$(MDL_CMD) --fix