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,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 | ||
matifali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 }} | ||
|
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"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,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 | ||
| } |
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 |
|---|---|---|
| @@ -1 +1,2 @@ | ||
| <!-- markdownlint-disable MD041 --> | ||
| [https://coder.com/docs/contributing/CODE_OF_CONDUCT](https://coder.com/docs/contributing/CODE_OF_CONDUCT) |
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 +1,2 @@ | ||
| <!-- markdownlint-disable MD041 --> | ||
| [https://coder.com/docs/CONTRIBUTING](https://coder.com/docs/CONTRIBUTING) |
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 \ | ||
|
|
@@ -566,8 +576,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 \ | ||
|
|
@@ -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 "$@" | ||
| 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 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 \ | ||
|
|
@@ -769,15 +797,6 @@ provisioner/terraform/testdata/version: | |
| fi | ||
| .PHONY: provisioner/terraform/testdata/version | ||
|
|
||
|
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 | ||
|
|
||
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.