Evaluate rumdl as a possible replacement for markdownlint

Proposal

rumdl is a relatively new tool that aims to offer the same features as markdownlint, but written in Rust with huge speed improvements and additional features.

In initial tests, rumdl appears to be extremely fast and has additional rules built-in that we could make use of.

Let's start evaluating rumdl more seriously, as a potential replacement to our current tooling.

Background

We have been using markdownlint for over 6 years now, and it has served us well. This was a replacement to mdl which is a ruby gem that had false positives and was quite slow in comparison.

• Standardize Markdown via markdownlint in CE docs (gitlab-org/gitlab-foss#64352 - closed)
• Change mdl to markdownlint for docs linting (gitlab-org/gitlab-foss!31994 - merged)

In 2024, we switched from markdownlint to markdownlint-cli2, as it was the backend used in the VS Code plugin and better suited to our needs (but not a major difference):

• Tracking issue for upgrade to latest markdownli... (gitlab-org/gitlab-docs#1761 - closed)

Benefits

rumdl seems to have some big benefits over markdownlint:

• Extremely fast, completes in seconds over the full gitlab docs set.
  • rumdl check doc/ 9.29s user 0.66s system 212% cpu 4.679 total (with caching)
  • markdownlint-cli2 --config .markdownlint-cli2.yaml doc/**/*.md 86.60s user 1.90s system 113% cpu 1:18.15 total
• Catches issues that markdownlint misses. For example:
  • Lazy continuation lines that can cause incorrect rendering (often because the content author is not aware of how markdown renderers handle lazy continuation):
    • Fix and enforce proper list spacing in the docs (gitlab-org/gitlab#482475)
• Author is very active, and extremely responsive. For example:
  • https://github.com/rvben/rumdl/issues/295
  • https://github.com/rvben/rumdl/issues/356
• Has several additional rules that we like (the author seems aligned with our philosophy on how markdown should be formatted) and could make use of.
  • https://github.com/rvben/rumdl/blob/main/docs/markdownlint-comparison.md#rules-unique-to-rumdl
• Has extensions/support for many editors for local linting, including VS Code and Sublime Text:
  • https://rumdl.dev/usage/editors/
• Might be able to remove a separate dependency!
  • We use Lychee to lint crosslinks between pages, but it appears rumdl's MD057 rule could do this automatically.
  • Unlike Lychee, which either catches it with lefthook or pipeline failures (after the fact), this would get caught immediately in-editor.

Drawbacks

• Still very new without wide adoption (that we can see).
• Does not appear to support custom rules. We currently have one custom rule:
  • Add link path test to markdownlint (gitlab-org/gitlab!185086 - merged) (though perhaps this could be added to the base rumdl support if we ask for it).

Evaluation proces

Steps we can consider taking in the future when we want to evaluate rumdl:

1. Start testing rumdl in docs-gitlab-com
   • Add minimal .rumdl.toml file, with anything not default being carefully considered.
   • Add rumdl to mise.toml file.
   • Add rumdl to the docs linting image.
   • Add job to docs-gitlab-com to run rumdl against Markdown files in that project.
   • Results:
2. Repeat for team-tasks.
   • Results:
3. Repeat for gitlab-development-kit, to see how it goes for a bigger set of docs. Consider gitaly project too, or other smaller projects.
   • Results:

When evaluating the results, include:

• Speed comparison
• Anything edge cases (more caught, more missed)
• Configuration that needs to be considered.