- Notifications
You must be signed in to change notification settings - Fork1k
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
- Replace Prettier with markdownlint for documentation formatting.- Rename `docs-pr.yaml` to `docs-lint.yaml` for clarity.- Adjust `Makefile` to use `fmt/biome` instead of `fmt/prettier`.- Remove `.prettierignore` and `.prettierignore.include` files.- Apply markdownlint formatting across relevant documentation files.
- Restrict triggers to main branch and pull requests- Remove automatic fix option in markdownlint-cli2 command
3d065a5
to4cd592b
Compare- Update `setup-node` action to specify pnpm version.- Remove redundant node_modules installation command.- Use specific commit hashes for action versions in workflows.- Adjust paths in Makefile for better file management.
cd5fcdc
to0d41834
CompareThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
amazing- thanks@matifali !
🚀
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I note a number of heading changes (e.g.#
=>##
) -- are we sure this won't break any existing documentation links?
matifali commentedJan 2, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There is a Markdown rule against having multiple H1 headings in a file. Yes, it will not break Markdown anchors, which are independent of heading levels. |
-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.
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.
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.
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.
EdwardAngertJan 2, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
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 acat
orecho
(printf
?) thing, but something like:
cat<<<"$changed-files">"list-changed-files.txt"
There was a problem hiding this comment.
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.
.markdownlint.json Outdated
@@ -0,0 +1,18 @@ | |||
{ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Will add comments and convert to*.jsonc
.
@@ -20,7 +20,7 @@ | |||
"playwright:install": "playwright install --with-deps chromium", | |||
"playwright:test": "playwright test --config=e2e/playwright.config.ts", | |||
"playwright:test-ui": "playwright test --config=e2e/playwright.config.ts --ui $([[ \"$CODER\" == \"true\" ]] && echo --ui-port=7500 --ui-host=0.0.0.0)", | |||
"gen:provisioner": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./e2e/ --ts_proto_opt=outputJsonMethods=false,outputEncodeMethods=encode-no-creation,outputClientImpl=false,nestJs=false,outputPartialMethods=false,fileSuffix=Generated,suffix=hey -I ../provisionersdk/proto ../provisionersdk/proto/provisioner.proto && pnpm exec prettier --ignore-path '/dev/null' --cache --write './e2e/provisionerGenerated.ts'", | |||
"gen:provisioner": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./e2e/ --ts_proto_opt=outputJsonMethods=false,outputEncodeMethods=encode-no-creation,outputClientImpl=false,nestJs=false,outputPartialMethods=false,fileSuffix=Generated,suffix=hey -I ../provisionersdk/proto ../provisionersdk/proto/provisioner.proto", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I see prettier was removed here, but no alternative given it its place?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
./e2e/provisionerGenerated.ts
is a generated file so should not format I guess.
This is already in the ignore list of biome.
Line 8 in687b015
"e2e/**/*Generated.ts", |
Uh oh!
There was an error while loading.Please reload this page.
--postgres-auth password|awsiamrds, $CODER_PG_AUTH (default: password) | ||
Type of auth to use when connecting to postgres. For AWS RDS, using | ||
IAM authentication (awsiamrds) is recommended. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
These files must not be changed, probably best to not touch anything in anytestdata
folder. Although, if they changed as a result of changing the Go files then that's OK.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
What is the best way to do that?
These files are generated from code and so does the API and CLI docs. And to make the docs follow the rules this is an artifact.
I will further explore how best to deal with this.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
WARN = 3, | ||
ERROR = 4, | ||
UNRECOGNIZED = -1, | ||
TRACE = 0, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This file is incorrectly indented. It'll be annoying if a developer is making local changes here and the whole file is reformatted.
Uh oh!
There was an error while loading.Please reload this page.
+1 to what@matifali says here - totally reasonable question and good catch though. Whatever the number of |
c82df5a
tofe265eb
CompareAdded path exclusions to resolve issues with table formatting in `api/schema.md` and `api/templates.md`.
wow |
"out/", | ||
"test-results/", | ||
"e2e/**/*Generated.ts", | ||
"src/api/*Generated.ts", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
removing as we want to lint/fmt these files.
94f5d52
intomainUh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Removed dependence on
prettier
in favor ofmarkdownlint
andmarkdown-table-formatter
for markdown files.