## Proposal [`rumdl`](https://rumdl.dev/) 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`](https://github.com/DavidAnson/markdownlint) for over 6 years now, and it has served us well. This was a replacement to [`mdl`](https://github.com/markdownlint/markdownlint) which is a ruby gem that had false positives and was quite slow in comparison. - https://gitlab.com/gitlab-org/gitlab-foss/-/work_items/64352+ - https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31994+ 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): - https://gitlab.com/gitlab-org/gitlab-docs/-/work_items/1761+ ## 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): - https://gitlab.com/gitlab-org/gitlab/-/work_items/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](https://github.com/lycheeverse/lychee) to lint crosslinks between pages, but it appears rumdl's [MD057](https://github.com/rvben/rumdl/blob/main/docs/md057.md) 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: - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/185086+ (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: 1. [ ] 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.