Skip to content

Create ESLint plugin rules to enforce best Docusaurus practices #6472

@Josh-Cena

Description

@Josh-Cena

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    apprenticeIssues that are good candidates to be handled by a Docusaurus apprentice / traineedomain: dxRelated to developer experience of working on Docusaurus sitesfeatureThis is not a bug or issue with Docusausus, per se. It is a feature request for the future.good first issueIf you are just getting started with Docusaurus, this issue should be a good place to begin.status: accepting prThis issue has been accepted, and we are looking for community contributors to implement this

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions