Make a distributed eslint plugin to enforce best Docusaurus practices

Josh-Cena commented 2 years ago

Have you read the Contributing Guidelines on issues?

[X] 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:

no-dynamic-i18n-messages: ensures that all translate calls are plain text labels
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

[X] I'd be willing to do some initial work on this proposal myself.

slorber commented 2 years ago

yes we definitively want an eslint plugin 👍

dave-sh commented 2 years ago

Hello can I be assigned this issue?

Josh-Cena commented 2 years ago

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

Josh-Cena commented 2 years ago

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

Ash-KODES commented 2 years ago

can I contribute to this?

Josh-Cena commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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

Josh-Cena commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Okay got it @Josh-Cena

AnmolBansalDEV commented 2 years ago

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

Josh-Cena commented 2 years ago

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 commented 1 year ago

@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 commented 1 year ago

@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

facebook / docusaurus