chore: adopt markdownlint and markdown-table-formatter for *.md #15831
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| name: Docs CI | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| pull_request: | ||
|
|
||
| jobs: | ||
| docs: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2 97AE .1 | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Setup Node | ||
| uses: ./.github/actions/setup-node | ||
|
|
||
| - uses: tj-actions/changed-files@bab30c2299617f6615ec02a68b9a40d10bd21366 # v45.0.5 | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| id: changed-files | ||
| with: | ||
| files: "docs/**/*.md" | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| separator: "," | ||
|
|
||
| - name: lint | ||
| if: steps.changed-files.outputs.any_changed == 'true' | ||
| run: | | ||
| pnpm exec markdownlint-cli2 ${{ steps.changed-files.outputs.all_changed_files }} | ||
|
There was a problem hiding this comment. This works now but could at some point fail with a shell error: argument list too long. Using xargs is one option and maybe markdown-lint has some other built-in function. If a file has spaces that would also be problematic. |
||
|
|
||
| - 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 | ||
|
There was a problem hiding this comment. Same as before, you could just add xargs in front of pnpm here. You could use null instead of newline ( There was a problem hiding this comment. I like this - seems like it might make it easier to debug issues later too something like a commented out debug line that writes the env contents into a file? is that possible/useful? I'm not sure what it would specifically look like or if it's a cat <<< "$changed-files" > "list-changed-files.txt"
Member
Author
There was a problem hiding this comment. @mafredri I am leaving the suggestions here out of this PR. I need to learn the risks here and can address them in a follow-up PR. I also welcome you taking a jab at this. |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| { | ||
|
There was a problem hiding this comment. Does this file support json comment syntax? If yes, might be nice to detail why we change some of these rules. Otherwise it's could be nice to stick to stock settings as close as possible, given that it has sane defaults. There was a problem hiding this comment. Will add comments and convert to |
||
| "MD009": true, | ||
| "MD010": false, | ||
| "MD012": true, | ||
| "MD013": false, | ||
| "MD022": true, | ||
| "MD024": { "siblings_only": true}, | ||
| "MD029": false, | ||
| "MD031": true, | ||
| "MD033": false, | ||
| "MD034": true, | ||
| "MD036": true, | ||
| "MD041": false, | ||
| "MD045": true, | ||
| "MD052": false, | ||
| "MD055": false, | ||
| "MD056": false | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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", | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "redhat.vscode-yaml", | ||
| "tekumara.typos-vscode", | ||
| "zxh404.vscode-proto3" | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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/biome fmt/markdown | ||
| .PHONY: fmt | ||
|
|
||
| fmt/go: | ||
|
|
@@ -438,15 +438,16 @@ else | |
| endif | ||
| .PHONY: fmt/ts | ||
|
|
||
| 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/biome | ||
|
|
||
| fmt/terraform: $(wildcard *.tf) | ||
| echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET)" | ||
|
|
@@ -463,7 +464,13 @@ else | |
| endif | ||
| .PHONY: fmt/shfmt | ||
|
|
||
| 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 \ | ||
| provisioner/terraform/testdata/version \ | ||
| site/e2e/provisionerGenerated.ts \ | ||
| site/src/theme/icons.json \ | ||
|
|
@@ -563,8 +573,6 @@ gen/mark-fresh: | |
| docs/reference/cli/index.md \ | ||
| docs/admin/security/audit-logs.md \ | ||
| coderd/apidoc/swagger.json \ | ||
| site/e2e/provisionerGenerated.ts \ | ||
| site/src/theme/icons.json \ | ||
| examples/examples.gen.json \ | ||
|
|
@@ -653,11 +661,15 @@ 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 "$@" | ||
| 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 | ||
| cd site | ||
| ../scripts/pnpm_install.sh | ||
| pnpm exec biome format --write ../examples/examples.gen.json | ||
|
|
||
| coderd/rbac/object_gen.go: scripts/typegen/rbacobject.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go | ||
| tempdir=$(shell mktemp -d /tmp/typegen_rbac_object.XXXXXX) | ||
|
|
@@ -680,22 +692,32 @@ site/src/api/countriesGenerated.ts: scripts/typegen/countries.tstmpl scripts/typ | |
| docs/admin/integrations/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics | ||
| go run scripts/metricsdocgen/main.go | ||
| ./scripts/pnpm_install.sh | ||
| 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 markdownlint-cli2 --fix ./docs/reference/cli/*.md | ||
| pnpm exec markdown-table-formatter ./docs/reference/cli/*.md | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 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 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 \ | ||
|
|
@@ -756,15 +778,6 @@ scripts/ci-report/testdata/.gen-golden: $(wildcard scripts/ci-report/testdata/*) | |
| go test ./scripts/ci-report -run=TestOutputMatchesGoldenFile -update | ||
| touch "$@" | ||
|
|
||
|
There was a problem hiding this comment. Do our replacement commands obey There was a problem hiding this comment. most of the formatting is done by |
||
| test: | ||
| $(GIT_FLAGS) gotestsum --format standard-quiet -- -v -short -count=1 ./... | ||
| .PHONY: test | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.