(docs) Switch to remark-lint/remark-stringify for linting/formatting markdown

[tesseralis]

Description

Switch to remark-lint for the docs' Markdown linter and remark-stringify for formatting.

Motivation

The most pressing need for remark-lint is the ongoing effort to translate the Gatsby docs. There are specific style rules that need to be enforced in order for our translation process to work correctly:

• Mandating explicit heading IDs and autogenerating them ((www) Autogenerate explicit IDs for headings #20732)
• Preventing relative imports of MDX components (chore(www): Make components used in MDX globally available #20685)
• Ensuring that prose is always soft-wrapped (Add proseWrap: never option to prettier md parsing  #22688)

In addition to localization of the docs, remark-lint would be beneficial for enforcing many of the rules found in the Gatsby Style Guide, through the use of existing rules and possibly creating our own. We can prohibit certain strings and suggest alternatives, prevent non-descriptive-link-text or even limit the number of emoji used on a page!

Implementation

1. Install remark-lint and remark-stringify along with recommended rules and run them on the docs.
2. Add docs/ directory to .prettierignore and set lint-staged to run remark instead of prettier on markdown files.

Issues

remark-stringify is, to my knowledge, incompatible with Prettier and will format some things differently without any config option to change them. For example, prettier automatically escapes dollar signs ($ becomes \$) but remark-stringify does not, unless remark-math is installed. Prettier deletes lines in between link definitions, while remark adds newlines in between them. If we want to add remark-lint, we need to completely switch it out with prettier for the docs. We may need to add instructions to contributors, e.g. installing a remark-lint plugin for VS Code.

Alternative Solutions

The primary thing we want to enforce for localization is the explicit heading IDs. For this, the alternate solution is to just create a custom script to add the heading IDs. This was our initial plan, since it would be faster and need a lot less buy-in from the rest of Gatsby. But soon I realized that there were even more rules that would need to be enforced for translation, and it didn't make sense to create multiple one-off scripts for each of them, rather than relying on an existing framework with existing rules and plugins built in.

Related

Previous implementation: #18942 - This PR should be used as a reference, but it's pretty old and now has a lot of merge conflicts

[nik72619c]

@tesseralis can I work on this one ?

[tesseralis]

@nik72619c sure, go ahead!