Make a distributed eslint plugin to enforce best Docusaurus practices

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

I realized there are a few text labels in our repo that are accidentally not translated. This has happened a few times in the past as well (see #4542). It would be interesting if we can make an eslint plugin with two rules:

1. no-dynamic-i18n-messages: ensures that all translate calls are plain text labels
2. no-untranslated-text: ensures all text labels in JSX are wrapped by translate calls (may have lots of false positives, but interesting to see how close we can get)

See https://docusaurus.io/docs/next/i18n/tutorial#translate-your-react-code for some documentation of the mental model of translate APIs.

We can publish this plugin as @docusaurus/eslint-plugin, so users can use this for themselves, as well as plugin/theme authors.

We may even ensure more best practices:

• prefer-docusaurus-link: ensures @docusaurus/Link is used instead of a tags
• prefer-ideal-image: ensures @theme/IdealImage is used instead of img tags
• prefer-docusaurus-heading: ensures @theme/Heading is used instead of h2 tags
• no-hardcoded-src: ensures all src attributes are either require or useBaseUrl
• no-window-eq-undefined: forbid typeof window !== 'undefined' because this is not an adequate way to escape SSR

Self-service

• I'd be willing to do some initial work on this proposal myself.

[slorber]

yes we definitively want an eslint plugin 👍

[dave-sh]

Hello can I be assigned this issue?

[Josh-Cena]

@dave-sh Sure, please go ahead. You have a week to send your initial work. Good luck!

[Josh-Cena]

This issue is up for grabs again, since @dave-sh seems to be unavailable.

[Ash-KODES]

can I contribute to this?

[Josh-Cena]

@Ash-KODES Sure—again, the work needed is given in the description. If you have any doubts, you can ask on the Discord server. You have a week to send your initial work. Good luck!

[Josh-Cena]

Due to the unresponsive nature of these kinds of issues, if anyone wants to grab the issue, just send a PR directly. No need to ask for permissions.

[alceil]

I would like to take up this issue @Josh-Cena . I would require some pointers as well on solving this issue.

[Josh-Cena]

@alceil This issue would require you to have some understanding in developing ESLing plugins, or at least working with ASTs in general. Are you looking for pointers on how to develop an ESLint plugin, or just how to translate my issue description into more concrete demand? I can elaborate on the latter, but probably not on the former.

[Josh-Cena]

Also cc @armano2 not sure about your availability, but I guess you would like this? This issue would probably not be resolved in a while, so whenever you have time you can take a look

[alceil]

I would like some pointer on developing eslint plugins. I can get it done @Josh-Cena . Also I would like to know more about the issue

[Josh-Cena]

I don't have many good resources to share, but https://eslint.org/docs/developer-guide/working-with-plugins and other related docs there would be a good starting point. When I work on ESLint I also find the AST explorer quite useful (you should use the TS-ESLint parser + ESLint v8 Transform). The TS-ESLint playground is quite good as well, but since we don't use type-aware linting here, AST explorer should be more preferable since you can visualize fixers.

Now this issue does assume you have some understanding in ESLint (as I said), so I will not go through the 101s of working with ASTs or fixers. You can try to learn from the resources above—the API is quite straightforward (I'd say much better than Babel's, because the goal is much simpler).

[alceil]

Okay got it @Josh-Cena

[AnmolBansalDEV]

Okay, i see a PR merged, why is it still open? What else should be done? Thank you!

[Josh-Cena]

Please check the list in the issue description—there are a lot of missing features that could be implemented as follow-up. If you want to take a shot feel free to.

[SanGeeky]

@Josh-Cena I would like to work on this, is necessary to cover all the good practices mentioned, or can I submit the ones I can develop?

[mahendra1290]

@Josh-Cena can I work on these

no-hardcoded-src: ensures all src attributes are either require or useBaseUrl
no-window-eq-undefined: forbid typeof window !== 'undefined' because this is not an adequate way to escape SSR