feat(core): simplify plugin API, support route.props (experimental)

[slorber]

EXPERIMENTAL

This feature is considered experimental for now.

It is preferable that third-party plugin authors wait for it to become stable/documented before relying on it.

Motivation

The plugin API is currently needlessly complicated and confusing.

Even the most basic example involves too much ceremony:
https://docusaurus.io/docs/api/plugin-methods/lifecycle-apis

export default function friendsPlugin(context, options) {
  return {
    name: 'docusaurus-friends-plugin',
    async contentLoaded({content, actions}) {
      const {createData, addRoute} = actions;
      // Create friends.json
      const friends = ['Yangshun', 'Sebastien'];
      const friendsJsonPath = await createData(
        'friends.json',
        JSON.stringify(friends),
      );

      // Add the '/friends' routes, and ensure it receives the friends props
      addRoute({
        path: '/friends',
        component: '@site/src/components/Friends.js',
        modules: {
          // propName -> JSON file path
          friends: friendsJsonPath,
        },
        exact: true,
      });
    },
  };
}

We want to make this simpler, the user shouldn't need to think about filesystem paths and created modules, but just "declare" that the component/route should receive.

export default function friendsPlugin(context, options) {
  return {
    name: 'docusaurus-friends-plugin',
    async contentLoaded({content, actions}) {
      actions.addRoute({
        path: '/friends',
        component: '@site/src/components/Friends.js',
        exact: true,
        props: {
		  friends: ['Yangshun', 'Sebastien']
        }
      });
    },
  };
}

This new route.props API can already greatly simplify our own plugins.

Note: the route.modules API will remain useful when a module need to be shared between multiple routes. However, we'll later also refactor it to not use the confusing createData() API.

We'll progressively migrate all contentLoaded APIs toward a more declarative model, and eventually make it synchronous to ensure it does not perform any IO operation. This will further permit us to optimize the DX. We can bail out of useless computations if we have everything in memory instead of having to query the filesystem.

Test Plan

unit tests + dogfood on our own plugins

Test links

https://deploy-preview-10042--docusaurus-2.netlify.app/

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	eeef26a
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/661e630c65390f000868b645
😎 Deploy Preview	https://deploy-preview-10042--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 71	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 67	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 70	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 63	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 71	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report

[github-actions]

Size Change: -6.8 kB (0%)

Total Size: 1.59 MB

Filename	Size	Change
website/.docusaurus/registry.js	247 kB	-2.94 kB (-1%)
website/.docusaurus/routesChunkNames.json	109 kB	-1.08 kB (-1%)
website/build/assets/js/main.********.js	808 kB	-2.78 kB (0%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/codeTranslations.json	2 B
website/.docusaurus/docusaurus.config.mjs	26.7 kB
website/.docusaurus/globalData.json	91.2 kB
website/.docusaurus/i18n.json	930 B
website/.docusaurus/routes.js	156 kB
website/.docusaurus/site-metadata.json	2.17 kB
website/build/assets/css/styles.********.css	113 kB
website/build/index.html	38 kB

_{compressed-size-action}