bytecodealliance / bytecodealliance/component-docs
Define markdown convention/formatting rules
- Dominant language
- Rust
- Stars
- 137
- Forks
- 88
- Avg merge
- 5d 12h
- Merged PRs (30d)
- 4
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.
Contributor guide
Research direction
Start with CONTRIBUTING.md and a representative Markdown file from the repository. Compare mdformat, markdownlint, dprint with its Markdown plugin, and Prettier as proposed, then document the selected conventions and integrate the chosen check into CI so future Markdown output is checked automatically.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- ci-cd, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100