matrix-org / matrix-org/matrix.org
Add additonal markdown linter rules
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 616
- Forks
- 463
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 19
Description
After #3051 is merged, we will have rumdl as the linter to check that the markdown we use to add content to the matrix.org website is correct.
We can use additional rules to have slightly stricter checks. Stricter checks can mean the CI fails more often, which can be frustrating, but it also means it will catches small mistakes for us, small mistakes that can trip up some software.
I want to make sure the linter remains helpful and not unnecessarily annoying, so adding all the rules wouldn't make much sense.
The following rules strike me as interesting to catch insidious mistakes without being unnecessarily pedantic.
- MD022 to have blank lines around headings
- MD030 to have a space after the list marker (e.g.
* Fooand not*Foo) - MD031 to have blank lines around code fences
- MD032 to have blank lines around lists
- MD037 to ensure emphasis don't have spaces messing up with them
- MD038 to ensure we don't have spaces messing with code spans
- MD042 to ensure no empty links, because that's a sign something went wrong
- MD045 to ensure we have alt text for images
- MD056 to ensure tables have a consistent number of cols
- MD058 to ensure tables have blank lines around them
We can also use rule severity so the CI doesn't fail, but we at least get a warning if something is not right
Originally posted by @thibaultamartin in https://github.com/matrix-org/matrix.org/pull/3051#discussion_r2598040642
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing pull request #3051 and the rumdl configuration it introduces. Evaluate the unchecked rules MD032, MD037, and MD045, then determine appropriate severities for warnings versus CI failures. Done means the selected rules are configured and the matrix.org content checks report useful results without unnecessary failures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- ci-cd, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100