chore: adopt markdownlint and markdown-table-formatter for *.md (coder#15831)

Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>

Author: matifali

.github/workflows/docs-ci.yaml

@@ -0,0 +1,45 @@
+name: Docs CI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "**.md"
+      - ".github/workflows/docs-ci.yaml"
+
+  pull_request:
+    paths:
+      - "docs/**"
+      - "**.md"
+      - ".github/workflows/docs-ci.yaml"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+
+      - name: Setup Node
+        uses: ./.github/actions/setup-node
+
+      - uses: tj-actions/changed-files@bab30c2299617f6615ec02a68b9a40d10bd21366 # v45.0.5
+        id: changed-files
+        with:
+          files: |
+            docs/**
+            **.md
+          separator: ","
+
+      - name: lint
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          pnpm exec markdownlint-cli2 ${{ steps.changed-files.outputs.all_changed_files }}
+
+      - name: fmt
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          # markdown-table-formatter requires a space separated list of files
+          echo ${{ steps.changed-files.outputs.all_changed_files }} | tr ',' '\n' | pnpm exec markdown-table-formatter --check

.markdownlint.jsonc

@@ -0,0 +1,31 @@
+// Example markdownlint configuration with all properties set to their default value
+{
+	"MD010": { "spaces_per_tab": 4}, // No hard tabs: we use 4 spaces per tab
+
+	"MD013": false, // Line length: we are not following a strict line lnegth in markdown files
+
+	"MD024": { "siblings_only": true }, // Multiple headings with the same content:
+
+	"MD033": false, // Inline HTML: we use it in some places
+
+	"MD034": false, // Bare URL: we use it in some places in generated docs e.g.
+	// codersdk/deployment.go L597, L1177, L2287, L2495, L2533
+	// codersdk/workspaceproxy.go L196, L200-L201
+	// coderd/tracing/exporter.go L26
+	// cli/exp_scaletest.go L-9
+
+	"MD041": false, // First line in file should be a top level heading: All of our changelogs do not start with a top level heading
+	// TODO: We need to update /home/coder/repos/coder/coder/scripts/release/generate_release_notes.sh to generate changelogs that follow this rule
+
+	"MD052": false, // Image reference: Not a valid reference in generated docs
+	// docs/reference/cli/server.md L628
+
+	"MD055": false, // Table pipe style: Some of the generated tables do not have ending pipes
+	// docs/reference/api/schema.md
+	// docs/reference/api/templates.md
+	// docs/reference/cli/server.md
+
+	"MD056": false // Table column count: Some of the auto-generated tables have issues. TODO: This is probably because of splitting cell content to multiple lines.
+	// docs/reference/api/schema.md
+	// docs/reference/api/templates.md
+}

.prettierignore

@@ -1,16 +1,16 @@
 {
 	"recommendations": [
+		"biomejs.biome",
+		"bradlc.vscode-tailwindcss",
+		"DavidAnson.vscode-markdownlint",
+		"EditorConfig.EditorConfig",
+		"emeraldwalk.runonsave",
+		"foxundermoon.shell-format",
 		"github.vscode-codeql",
 		"golang.go",
 		"hashicorp.terraform",
-		"esbenp.prettier-vscode",
-		"foxundermoon.shell-format",
-		"emeraldwalk.runonsave",
-		"zxh404.vscode-proto3",
 		"redhat.vscode-yaml",
 		"tekumara.typos-vscode",
-		"EditorConfig.EditorConfig",
-		"biomejs.biome",
-		"bradlc.vscode-tailwindcss"
+		"zxh404.vscode-proto3"
 	]
 }

.prettierignore.include

@@ -1 +1,2 @@
-[https://coder.com/docs/coder-oss/latest/contributing/CODE_OF_CONDUCT](https://coder.com/docs/contributing/CODE_OF_CONDUCT)
+<!-- markdownlint-disable MD041 -->
+[https://coder.com/docs/contributing/CODE_OF_CONDUCT](https://coder.com/docs/contributing/CODE_OF_CONDUCT)

.vscode/extensions.json

@@ -1 +1,2 @@
-https://coder.com/docs/CONTRIBUTING
+<!-- markdownlint-disable MD041 -->
+[https://coder.com/docs/CONTRIBUTING](https://coder.com/docs/CONTRIBUTING)

CODE_OF_CONDUCT.md

@@ -414,7 +414,7 @@ BOLD := $(shell tput bold 2>/dev/null)
 GREEN := $(shell tput setaf 2 2>/dev/null)
 RESET := $(shell tput sgr0 2>/dev/null)
 
-fmt: fmt/ts fmt/go fmt/terraform fmt/shfmt fmt/prettier
+fmt: fmt/ts fmt/go fmt/terraform fmt/shfmt fmt/biome fmt/markdown
 .PHONY: fmt
 
 fmt/go:
@@ -438,15 +438,16 @@ else
 endif
 .PHONY: fmt/ts
 
-fmt/prettier: .prettierignore
-	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/prettier$(RESET)"
+fmt/biome:
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/biome$(RESET)"
+	cd site
 # Avoid writing files in CI to reduce file write activity
 ifdef CI
 	pnpm run format:check
 else
 	pnpm run format
 endif
-.PHONY: fmt/prettier
+.PHONY: fmt/biome
 
 fmt/terraform: $(wildcard *.tf)
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET)"
@@ -463,7 +464,13 @@ else
 endif
 .PHONY: fmt/shfmt
 
-lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons
+fmt/markdown:
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET)"
+	./scripts/pnpm_install.sh
+	pnpm format-docs
+.PHONY: fmt/markdown
+
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown
 .PHONY: lint
 
 lint/site-icons:
@@ -497,6 +504,11 @@ lint/helm:
 	make lint
 .PHONY: lint/helm
 
+lint/markdown:
+	./scripts/pnpm_install.sh
+	pnpm lint-docs
+.PHONY: lint/markdown
+
 # All files generated by the database should be added here, and this can be used
 # as a target for jobs that need to run after the database is generated.
 DB_GEN_FILES := \
@@ -530,8 +542,6 @@ GEN_FILES := \
 	docs/reference/cli/index.md \
 	docs/admin/security/audit-logs.md \
 	coderd/apidoc/swagger.json \
-	.prettierignore.include \
-	.prettierignore \
 	provisioner/terraform/testdata/version \
 	site/e2e/provisionerGenerated.ts \
 	site/src/theme/icons.json \
@@ -566,8 +576,6 @@ gen/mark-fresh:
 		docs/reference/cli/index.md \
 		docs/admin/security/audit-logs.md \
 		coderd/apidoc/swagger.json \
-		.prettierignore.include \
-		.prettierignore \
 		site/e2e/provisionerGenerated.ts \
 		site/src/theme/icons.json \
 		examples/examples.gen.json \
@@ -648,6 +656,9 @@ vpn/vpn.pb.go: vpn/vpn.proto
 site/src/api/typesGenerated.ts: $(wildcard scripts/apitypings/*) $(shell find ./codersdk $(FIND_EXCLUSIONS) -type f -name '*.go')
 	# -C sets the directory for the go run command
 	go run -C ./scripts/apitypings main.go > $@
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write src/api/typesGenerated.ts
 
 site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisionersdk/proto/provisioner.pb.go
 	cd site
@@ -656,8 +667,9 @@ site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisio
 
 site/src/theme/icons.json: $(wildcard scripts/gensite/*) $(wildcard site/static/icon/*)
 	go run ./scripts/gensite/ -icons "$@"
-	./scripts/pnpm_install.sh
-	pnpm -C site/ exec biome format --write src/theme/icons.json
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write src/theme/icons.json
 
 examples/examples.gen.json: scripts/examplegen/main.go examples/examples.go $(shell find ./examples/templates)
 	go run ./scripts/examplegen/main.go > examples/examples.gen.json
@@ -676,29 +688,45 @@ codersdk/rbacresources_gen.go: scripts/typegen/codersdk.gotmpl scripts/typegen/m
 
 site/src/api/rbacresourcesGenerated.ts: scripts/typegen/codersdk.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
 	go run scripts/typegen/main.go rbac typescript > "$@"
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write src/api/rbacresourcesGenerated.ts
 
 site/src/api/countriesGenerated.ts: scripts/typegen/countries.tstmpl scripts/typegen/main.go codersdk/countries.go
 	go run scripts/typegen/main.go countries > "$@"
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write src/api/countriesGenerated.ts
 
 docs/admin/integrations/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
 	go run scripts/metricsdocgen/main.go
 	./scripts/pnpm_install.sh
-	pnpm exec prettier --write ./docs/admin/integrations/prometheus.md
+	pnpm exec markdownlint-cli2 --fix ./docs/admin/integrations/prometheus.md
+	pnpm exec markdown-table-formatter ./docs/admin/integrations/prometheus.md
 
 docs/reference/cli/index.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
 	CI=true BASE_PATH="." go run ./scripts/clidocgen
 	./scripts/pnpm_install.sh
-	pnpm exec prettier --write ./docs/reference/cli/index.md ./docs/reference/cli/*.md ./docs/manifest.json
+	pnpm exec markdownlint-cli2 --fix ./docs/reference/cli/*.md
+	pnpm exec markdown-table-formatter ./docs/reference/cli/*.md
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write ../docs/manifest.json
 
 docs/admin/security/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
 	go run scripts/auditdocgen/main.go
 	./scripts/pnpm_install.sh
-	pnpm exec prettier --write ./docs/admin/security/audit-logs.md
+	pnpm exec markdownlint-cli2 --fix ./docs/admin/security/audit-logs.md
+	pnpm exec markdown-table-formatter ./docs/admin/security/audit-logs.md
 
 coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
 	./scripts/apidocgen/generate.sh
 	./scripts/pnpm_install.sh
-	pnpm exec prettier --write ./docs/reference/api ./docs/manifest.json ./coderd/apidoc/swagger.json
+	pnpm exec markdownlint-cli2 --fix ./docs/reference/api/*.md
+	pnpm exec markdown-table-formatter ./docs/reference/api/*.md
+	cd site
+	../scripts/pnpm_install.sh
+	pnpm exec biome format --write ../docs/manifest.json ../coderd/apidoc/swagger.json
 
 update-golden-files: \
 	cli/testdata/.gen-golden \
@@ -769,15 +797,6 @@ provisioner/terraform/testdata/version:
 	fi
 .PHONY: provisioner/terraform/testdata/version
 
-# Combine .gitignore with .prettierignore.include to generate .prettierignore.
-.prettierignore: .gitignore .prettierignore.include
-	echo "# Code generated by Makefile ($^). DO NOT EDIT." > "$@"
-	echo "" >> "$@"
-	for f in $^; do
-		echo "# $${f}:" >> "$@"
-		cat "$$f" >> "$@"
-	done
-
 test:
 	$(GIT_FLAGS) gotestsum --format standard-quiet -- -v -short -count=1 ./...
 .PHONY: test