Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Make a distributed eslint plugin to enforce best Docusaurus practices #6472

Open
2 tasks done
Josh-Cena opened this issue Jan 26, 2022 · 17 comments
Open
2 tasks done

Make a distributed eslint plugin to enforce best Docusaurus practices #6472

Josh-Cena opened this issue Jan 26, 2022 · 17 comments
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee domain: dx Related to developer experience of working on Docusaurus sites feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. good first issue If you are just getting started with Docusaurus, this issue should be a good place to begin. status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this

Comments

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented Jan 26, 2022 •
edited

Have you 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.
@Josh-Cena Josh-Cena added good first issue If you are just getting started with Docusaurus, this issue should be a good place to begin. proposal This issue is a proposal, usually non-trivial change status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this labels Jan 26, 2022
@Josh-Cena Josh-Cena mentioned this issue Jan 27, 2022
Merged
@slorber
Copy link
Collaborator

slorber commented Jan 27, 2022

yes we definitively want an eslint plugin 👍

@Josh-Cena Josh-Cena changed the title Make a distributed eslint plugin to check for i18n labels Make a distributed eslint plugin to enforce best Docusaurus practices Jan 27, 2022
@dave-sh
Copy link

dave-sh commented Jan 28, 2022

Hello can I be assigned this issue?

@Josh-Cena
Copy link
Collaborator Author

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

@Josh-Cena Josh-Cena added status: claimed Issue has been claimed by a contributor who plans to work on it. and removed status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this labels Jan 29, 2022
@Josh-Cena Josh-Cena added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. and removed proposal This issue is a proposal, usually non-trivial change labels Jan 31, 2022
@Josh-Cena
Copy link
Collaborator Author

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

@Josh-Cena Josh-Cena added status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this and removed status: claimed Issue has been claimed by a contributor who plans to work on it. labels Feb 5, 2022
@Ash-KODES
Copy link

can I contribute to this?

@Josh-Cena
Copy link
Collaborator Author

@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 Josh-Cena added status: claimed Issue has been claimed by a contributor who plans to work on it. and removed status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this labels Feb 25, 2022
@Josh-Cena Josh-Cena added status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this and removed status: claimed Issue has been claimed by a contributor who plans to work on it. labels Mar 5, 2022
@Josh-Cena
Copy link
Collaborator Author

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.

@Josh-Cena Josh-Cena added the domain: dx Related to developer experience of working on Docusaurus sites label Mar 29, 2022
@alceil
Copy link

alceil commented Apr 1, 2022

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

@Josh-Cena
Copy link
Collaborator Author

Josh-Cena commented Apr 1, 2022 •
edited

@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
Copy link
Collaborator Author

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
Copy link

alceil commented Apr 1, 2022 •
edited

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
Copy link
Collaborator Author

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
Copy link

alceil commented Apr 1, 2022

Okay got it @Josh-Cena

@elias-pap elias-pap mentioned this issue Apr 18, 2022
Merged
@AnmolBansalDEV
Copy link

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

@Josh-Cena
Copy link
Collaborator Author

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
Copy link

SanGeeky commented Sep 30, 2022 •
edited

@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?

@JohnVicke JohnVicke mentioned this issue Oct 1, 2022
Merged
2 tasks
@Devansu-Yadav Devansu-Yadav mentioned this issue Nov 28, 2022
Merged
3 tasks
@Devansu-Yadav Devansu-Yadav mentioned this issue Mar 25, 2023
Draft
3 tasks
@mahendra1290
Copy link

@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

@slorber slorber added the apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee label Sep 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee domain: dx Related to developer experience of working on Docusaurus sites feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. good first issue If you are just getting started with Docusaurus, this issue should be a good place to begin. status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
8 participants
@slorber @SanGeeky @mahendra1290 @dave-sh @alceil @Josh-Cena @Ash-KODES @AnmolBansalDEV