Repository navigation
Define markdown convention/formatting rules #292
Description
It would be good to define our standards/expectations for markdown formatting somewhere consistently.
A good place for this would be CONTRIBUTING.md, but other places could work too.
In addition to introducing documentation on how markdown should be written in the repo, we should probably try and
implement some tooling that enables machines to check our output for us:
- https://github.com/hukkin/mdformat
- https://github.com/DavidAnson/markdownlint
- https://dprint.dev/overview/ w/ https://github.com/dprint/dprint-plugin-markdown
- Prettier (listed last because it's intentionally hard to configure)
I think a good PR that resolves this issue would have a comparison of the output of these tools on one of our files, along with integration of the tool into CI so that we can catch issues going forward.
Activity
vados-cosmonic commentedon Jul 30, 2025
@mkatychev hey do you have some opinions here?
@itowlson @kate-goldenring would also like your feedback here
One thing that is probably in scope for this issue/the resulting PR is coming up with a style:
I like the introduction of Semantic line breaks by @catamorphism , but we probably need to be a bit more structured about it. Having a section that can essentially say "prefer this organization to that" would be very useful for code review/ensuring consistent style.
mkatychev commentedon Jul 30, 2025
@vados-cosmonic I think a row line limit would be nice, something like 100 lines to improve readability in a text editor. I'll take a look at the markdown linters you've mentioned in the issue.
vados-cosmonic commentedon Jul 30, 2025
Thanks! Yeah I'm not sure which one is the best one to use, but they all seem reasonable -- appreciate you diving in and checking them out!