Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 94 commits into from
Jan 3, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
94 commits
Select commit Hold shift + click to select a range
fe34c79
disable prettier for docs md
EdwardAngert Nov 25, 2024
5d1429a
make fmt
EdwardAngert Nov 25, 2024
a8b2217
fix md in jfrog-artifactory
EdwardAngert Nov 25, 2024
8df4ea1
Merge remote-tracking branch 'origin/main' into 216-disable-prettier-…
Dec 5, 2024
819074c
add markdownlint-cli2 and rules
Dec 5, 2024
150fdef
make fmt
Dec 5, 2024
4a1fb29
fix typo
Dec 5, 2024
acee64b
alt text to contributors
Dec 5, 2024
9109a7e
Apply suggestions from code review
EdwardAngert Dec 6, 2024
a6b8f83
move action; remove output format
Dec 6, 2024
6e8aa60
link fixes
Dec 6, 2024
9f14438
fixes and ignore no-bare-urls
Dec 6, 2024
40a94f1
md fixes
Dec 6, 2024
43435a5
add changed.yml
Dec 9, 2024
1da5f23
md lint changed files
Dec 9, 2024
59a92c9
remove redundancy from docs-pr.yaml
Dec 9, 2024
34ca8cb
mdlinter ignore docs/reference
EdwardAngert Dec 10, 2024
4dc14ea
fix errors
EdwardAngert Dec 10, 2024
b7331df
Merge branch 'main' into 216-disable-prettier-docs-md
matifali Dec 11, 2024
fcaa917
Integrate markdownlint and remove Prettier for docs
matifali Dec 11, 2024
e9431a6
Refactor docs lint workflow in docs-lint.yaml
matifali Dec 11, 2024
2f84e0f
Update docs lint workflow to include site directory
matifali Dec 11, 2024
e3ac0b1
Add packageManager to site package.json
matifali Dec 11, 2024
9ccfcfd
Refactor actions and workflows for consistency
matifali Dec 11, 2024
7d5b411
Remove pnpm-lock.yaml from version control
matifali Dec 11, 2024
3b396d3
Fix markdown lint issues in docs and Makefile
matifali Dec 11, 2024
44ceda1
Remove comment line handling in example parsing
matifali Dec 11, 2024
847a8f3
Quote markdownlint path globs in Makefile
matifali Dec 11, 2024
4ed47fc
Fix formatting in provisionerGenerated.ts
matifali Dec 11, 2024
89fec9a
Merge remote-tracking branch 'origin/main' into 216-disable-prettier-…
EdwardAngert Dec 11, 2024
6d5006a
Refactor TypeScript formatting target in Makefile
matifali Dec 12, 2024
0471071
Refactor Makefile to rename fmt/ts to fmt/biome
matifali Dec 12, 2024
981d7b5
Refactor documentation for consistency in formatting
matifali Dec 12, 2024
d11102a
Rename docs-lint.yaml to docs-ci.yaml
matifali Dec 12, 2024
e14d543
Discard changes to .github/actions/setup-node/action.yaml
matifali Dec 12, 2024
f1305d0
Discard changes to coderd/prometheusmetrics/testdata/agent-stats.json
matifali Dec 12, 2024
3670fa7
Discard changes to coderd/prometheusmetrics/insights/testdata/insight…
matifali Dec 12, 2024
e1eec2f
revert non-docs chnages
matifali Dec 12, 2024
f3652f7
remove prettier
matifali Dec 12, 2024
34ceccf
ignore examples.gen.json
matifali Dec 12, 2024
868d3fa
Merge branch '216-disable-prettier-docs-md' into atif/bye-bye-prettier
matifali Dec 12, 2024
3c2c4da
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 12, 2024
8cdd668
Update markdown formatting tools and apply fixes
matifali Dec 12, 2024
223cd4d
ci: specify workspace directory in setup-node action
matifali Dec 12, 2024
6de5e1d
Add Storybook launch script to package.json
matifali Dec 12, 2024
2ed285f
Rename docs lint workflow to docs CI
matifali Dec 12, 2024
eb3504c
Remove redundant setup-node configuration
matifali Dec 12, 2024
7b7308b
Add echo for changed files in docs CI workflow
matifali Dec 12, 2024
95d5574
Fix workflow environment variable syntax in docs CI
matifali Dec 12, 2024
d8fb439
Swap lint and fmt steps in docs workflow
matifali Dec 12, 2024
db200bb
Rename workflow job to 'docs' in docs-ci.yaml
matifali Dec 12, 2024
60a5a4a
Improve markdown formatting consistency
matifali Dec 12, 2024
691cf5c
Refactor JSON example tags formatting and add comment
matifali Dec 12, 2024
c9afb8b
Add generated examples for various environments
matifali Dec 12, 2024
79abf5f
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 17, 2024
7a326bd
`make fmt`
matifali Dec 17, 2024
f6c652a
Resolve merge conflict by incorporating both suggestions
matifali Dec 23, 2024
ab64ced
fix glob
matifali Dec 23, 2024
fd042dd
fix glob
matifali Dec 23, 2024
c9bc320
fixup: remove extra examples.gen.json from root
matifali Dec 23, 2024
a38312a
JSON do not have commnets
matifali Dec 23, 2024
3417860
remove target for ignored file
matifali Dec 23, 2024
bd31583
make -B
matifali Dec 23, 2024
9b0f28a
fixup
matifali Dec 24, 2024
917d6b3
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 24, 2024
ad73e4e
fixup
matifali Dec 24, 2024
90acaca
Reorder and update VSCode extension recommendations
matifali Dec 27, 2024
979a283
enable more rules
matifali Dec 27, 2024
34aa71b
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 27, 2024
6abc05a
make gen
matifali Dec 27, 2024
a291686
make fmt
matifali Dec 27, 2024
a61d20d
golden files
matifali Dec 30, 2024
e384d0a
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 30, 2024
f0cb88d
Update URLs to angle brackets for Markdown
matifali Dec 30, 2024
4e83922
Update codersdk/deployment.go
matifali Dec 31, 2024
504a1ed
Update docs/changelogs/v2.1.1.md
matifali Dec 31, 2024
4cea376
Update docs/changelogs/v2.5.0.md
matifali Dec 31, 2024
1637783
Merge branch 'main' into atif/bye-bye-prettier
matifali Dec 31, 2024
5392bb7
fix heading levels in IDP sync documentation
matifali Dec 31, 2024
15f21eb
Update docs CI workflow for specific file paths
matifali Dec 31, 2024
b733ad1
Format code examples in docs with backticks
matifali Dec 31, 2024
0d41834
Update workflow paths for consistent globbing
matifali Dec 31, 2024
f97ce22
Merge branch 'main' into atif/bye-bye-prettier
matifali Jan 2, 2025
687b015
wip
matifali Jan 2, 2025
fe265eb
wip 2
matifali Jan 2, 2025
33f4b81
fixup
matifali Jan 2, 2025
11dd374
Update markdownlint config for schema and templates docs
matifali Jan 2, 2025
43f568b
Merge branch 'main' into atif/bye-bye-prettier
matifali Jan 3, 2025
dadc689
make -B gen
matifali Jan 3, 2025
c375423
Delete coderd/database/dbmock/gomock_reflect_2684282611/prog.go
matifali Jan 3, 2025
6b95860
make -B gen
matifali Jan 3, 2025
8fefeef
make -B gen
matifali Jan 3, 2025
8731666
make update-golden-files
matifali Jan 3, 2025
9f6adaa
fixup
matifali Jan 3, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .github/workflows/docs-ci.yaml
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
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 }}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as before, you could just add xargs in front of pnpm here. You could use null instead of newline (tr , ’\0’, xargs -0) for additional safety. For ultimate safety, store files in env via yaml and echo the env in addition to null handling and all bases are covered.

Copy link
Contributor

@EdwardAngert EdwardAngert Jan 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 or echo (printf?) thing, but something like:

cat <<< "$changed-files" > "list-changed-files.txt"

Copy link
Member Author

@matifali matifali Jan 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

31 changes: 31 additions & 0 deletions .markdownlint.jsonc
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
}
96 changes: 0 additions & 96 deletions .prettierignore

This file was deleted.

14 changes: 0 additions & 14 deletions .prettierignore.include

This file was deleted.

14 changes: 7 additions & 7 deletions .vscode/extensions.json
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",
"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"
]
}
3 changes: 2 additions & 1 deletion CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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)
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
https://coder.com/docs/CONTRIBUTING
<!-- markdownlint-disable MD041 -->
[https://coder.com/docs/CONTRIBUTING](https://coder.com/docs/CONTRIBUTING)
67 changes: 43 additions & 24 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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)"
Expand All @@ -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:
Expand Down Expand Up @@ -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 := \
Expand Down Expand Up @@ -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 \
Expand Down Expand Up @@ -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 \
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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 \
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do our replacement commands obey .gitignore now that we don't use prettier/.prettierignore?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

most of the formatting is done by biome and it supports .gitignore. I need to configure it though.
See: https://biomejs.dev/reference/configuration/#vcsuseignorefile


test:
$(GIT_FLAGS) gotestsum --format standard-quiet -- -v -short -count=1 ./...
.PHONY: test
Expand Down
Loading
Loading