matrix-org / matrix-org/matrix.org

Add additonal markdown linter rules

Open
#3,058 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement good first issue help wanted
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. * Foo and 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.