Support shorthand for themes/plugins/presets configuration

[fsmaia]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

When configuring a theme, plugin, or preset, instead of looking up for the NPM package itself, we could have a chain of NPM package resolve attempts, in the respective order/priority:

1. docusaurus-theme-{theme}
2. @docusaurus/theme-{theme}
3. @{theme}/docusaurus-theme
4. {theme}

The same for plugins and presets.

Example docusaurus configuration:

module.exports = {
  themes: ['classic'],
};

Package resolve attempts:

1. docusaurus-theme-classic
2. @docusaurus/theme-classic
3. @classic/docusaurus-theme
4. classic

PS.: it is not clear to me if we should lookup for scoped packages only when the user input begins with @, so there are two alternatives:
A: themes: ['@org'] -> @org/docusaurus-theme (resolvers chain, as of the numbered list above: 3)
B: themes: ['org'] -> @org/docusaurus-theme (resolvers chain, as of the numbered list above: 1, 2, 3, 4)

Has this been requested on Canny?

https://docusaurus.io/feature-requests/p/shorthand-for-themespluginspresets-configuration

Motivation

Some modern tools are adopting the "shareable config" concept, generally supporting shorthand, so the user may omit the keywords that may be inferred, e.g. eslint-config-{config}, eslint-plugin-{plugin}.

This also encourages developers to publish their packages in a canonical way (including docusaurus-(theme|plugin|preset) in the name), so a GitHub or NPM search would result in way more packages, therefore increasing their reusability and popularity.

Reference:
https://eslint.org/docs/developer-guide/shareable-configs

API design

I guess the API design is pretty straightforward: users may omit the following keywords in their configuration:

• docusaurus-theme
• docusaurus-plugin
• docusaurus-preset

About the implementation itself, we could use ESLint as the baseline:
https://github.com/eslint/eslintrc/blob/main/lib/shared/naming.js#L14

Or thinking in a more ambitious way, we could have a dedicated package/repository to that, just like cosmiconfig, which does the same, but for configuration file names lookup.

Have you tried building it?

No response

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

This would be cool to have. Have you done some field research about how Docusaurus packages look like in the wild? Is @{theme}/docusaurus-theme really a widely used pattern?

[fsmaia]

I took a look. In the NPM, there are 27 packages, and just one is using @{scope}/docusaurus-theme, but there are some using the @{scope}/docusaurus-theme-{theme}, which makes me think that this could be a resolve attempt too, when inputting @{scope}/{theme}.

Although unpopular, it seems to me that @{scope}/docusaurus-theme would be very useful, for companies that wish to standardize the theme to all the Docusaurus instances.

[fsmaia]

May I implement it and open a PR?

[Josh-Cena]

@fsmaia I'm personally in favor of this but let's hear from @slorber as well. Three things I'm not sure of though:

1. Should we try to resolve @docusaurus/theme-{theme} before docusaurus-theme-{theme} since the former is the convention of official Docusaurus packages?
2. Should we include docusaurus-{theme} (without the theme- prefix) because it also seems to be widely used?
3. I don't really like the @{theme}/docusaurus-theme one. It's not a widely used pattern in the wild and it... doesn't make much sense to me

[slorber]

That's worth doing a POC, see how complex it would be to support and apply to our own config file 👍

I'd rather not introduce too many fallback patterns but rather only a few ones so that the naming convention the community uses is consistent and there's not much possible naming choices if you want shorthand to work

[fsmaia]

1. Should we try to resolve @docusaurus/theme-{theme} before docusaurus-theme-{theme} since the former is the convention of official Docusaurus packages?

For sure!

2. Should we include docusaurus-{theme} (without the theme- prefix) because it also seems to be widely used?

IMHO no, we should encourage developers to move their packages to be adherent to the naming convention, and then this would give the main benefits (raising popularity and discoverability)

3. I don't really like the @{theme}/docusaurus-theme one. It's not a widely used pattern in the wild and it... doesn't make much sense to me

The @{scope}/docusaurus-theme is interesting because companies usually use the scope to hold several company-level definitions/plugins/presets, such as:

• @company/docusaurus-theme
• @company/eslint-config
• @company/eslint-plugin
• @company/prettier-config

In a generic way, after the scopes started being widely used, it seems to me that:

• {tool}-{config|plugin|theme}-{keyword} (e.g. docusaurus-theme-classic) usually addresses a specific feature, behavior, or customization (in this case it means that this theme looks like classic)
• @{company}/{tool}-{config|plugin|theme} (e.g. @facebook/docusaurus-theme) usually addresses a company's guidelines/tooling, without any specific characteristic
• @{company}/{tool}-{config|plugin|theme}-{keyword} (e.g. @facebook/docusaurus-theme-dark) usually addresses a specific feature within a company (this case is far less used, and I agree about not including this in the PR)

I guess this is the rationale behind ESLint shareable config resolvers (and other tools too, if you will I can bring more references in the community), and IMHO it makes a lot of sense.

[fsmaia]

To validate the idea and an implementation suggestion, I started a draft PR.

As you guys adds suggestions, I'll apply the same behavior for themes and presets