Add custom replace rule to markdownlint configuration

[OnkarRuikar]

There are many unwanted characters that we've been replacing time to time. For example, #16324, #16770 (comment), #17834 (review) are some of the PRs.
Because of some locales or keyboard settings contributors introduce such characters.

We want to handle cases such as:

• curly double quotes “ to straight quotes " curly -> straight apostrophes #16770
• curly single quotes ‘ and ’ to straight quote '
• double hyphens -- to m-dash — -- to m-dash #17833
• three dots ... to ellipsis …
• replace (en-US/docs with (/en-US/docs to avoid broken links fix a broken link #18670 (comment)
• remove trailing spaces. Fix two+ trailing spaces in text #19866
• and recently Missing spaces batch 3 #18123 (comment)

The PR adds a custom markdownlint rule/plugin markdownlint-rule-search-replace to address such issues.

With the search-replace rule in place we can run the linter like this:

# to flag the issues
yarn lint:md

# or to fix automatically
yarn fix:md

We can provide plain string or regex pattern to search and replace. So many complex cases can be handled.
Refer the rule documentation for more information.

To see the plugin in action refer #18210.

---

cc/ @teoli2003 , @nschonni , @caugner

[teoli2003]

We have to pay attention to two things:

• exceptions. For example, there is a page that speaks about curly braces, and this shouldn't be replaces
• for...of, for...in, etc. These 3 dots shouldn't be replaced by an ellipsis.

So I think we should be conservative or have a way to skip pages (for the first case). And we should skip code snippets (areas enclosed with 1 or 3 backticks)

Finally, like always we must clean MDN first, before adding automation. As this was already cleaned not too long ago, this shouldn't be too difficult.

[OnkarRuikar]

#12316 probably needs to be addressed first,

Currently developers refer to only .markdownlint.json from mdn/content for the markdown linting. And they install markdownlint-cli globally themselves.
As the linting happens manually at the moment and it is not affecting any other workflows, we can merge this PR to make the feature available. We do not have to block this PR for #12316.

[OnkarRuikar]

All, I've rebased and updated the lock file. Also added new rules as per our recent experiences.

Added new rules to fix

• internal links that are not relative
• trailing spaces (markdownlinter doesn't flag/fix more than one trailing space)

Using this we've merged following PR

• Fix typos #19964

[teoli2003]

Can you rebase this PR? There are merge conflicts and warnings that I think were fixed elsewhere.

[teoli2003]

This PR will flag these legitimate uses of curly braces forever, or am I wrong?

[teoli2003]

Or maybe we should remove this rule from the guide as it will automatically be fixed by Markdownlint. @dipikabh @wbamberg, any thoughts?

[OnkarRuikar]

This PR will flag these legitimate uses of curly braces forever, or am I wrong?

Yes.

There are two options to solve this:

• A. Use HTML codes (it works in our setup): Use “, &rdquo, and ’ for curly quotes when needed #18009

  - **Incorrect**: Please don’t use “curly quotes.”
  

• B. Use magic comments: (we've been already using these https://github.com/mdn/content/search?q=markdownlint-disable)

  <!-- markdownlint-disable search-replace -->
  
  - **Incorrect**: Please don’t use “curly quotes.”
  
  <!-- markdownlint-enable search-replace -->
  

[teoli2003]

I think we should use HTML escape sequences in these rare cases: see #17988

[OnkarRuikar]

All the lint errors, that were being flagged by this plugin, have been fixed.

[nschonni]

I'm not sure if https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionscustomrules is available in the config without migrating to the the CLI2 https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2jsonc. Reason I haven't switched to the CLI2 is the lack of a --fix flag on the commandline, so you need a whole other config object (that could inherit from a base), which seems awkward.

I really like the quote rules and the URL ones, I'm a little -0 on the elipsis and m-dash ones.

[github-actions]

Preview URLs

• https://pr17988.content.dev.mdn.mozit.cloud/en-US/docs/Web/CSS/border

Flaws

None! 🎉

External URLs

URL: /en-US/docs/Web/CSS/border
Title: border
on GitHub

No new external URLs

(this comment was updated 2022-09-01 06:07:07.801741)

[OnkarRuikar]

I'm not sure if DavidAnson/markdownlint@main/README.md#optionscustomrules is available in the config...

Actually, we are using https://github.com/igorshubovych/markdownlint-cli project for our linting and not https://github.com/DavidAnson/markdownlint (not directly).

And markdownlint-cli does have option (-r) to specify custom rule package:

markdownlint -r markdownlint-rule-search-replace --fix "mymdfile.md"

---

The PR does work. I've deliberately committed the typos to the PR in deleberate error for testing commit.
And it has flagged the errors as expected:

• The fix option also works: Daily markdownlint #20194

---

I'm a little -0 on the elipsis and m-dash ones.

ellipsis - we are not adding any rule related to ellipsis in this PR.
m-dash - the rule will only work on text content not code blocks. All m-dashes have been fixed in the repo at the moment, so it's good to go.

[dipikabh]

Or maybe we should remove this rule from the guide as it will automatically be fixed by Markdownlint. @dipikabh @wbamberg, any thoughts?

Yes, I think we can remove that rule from the guide (just like we've done for the things Prettier automatically fixes).

[teoli2003]

LGTM, but let's not merge this during the weekend as we are not here to deal with unexpected problems.