feat(core): add new plugin allContentLoaded lifecycle

[slorber]

Important: this feature is considered experimental, and is for now undocumented. Please only use it on your own site plugins, and avoid publishing third-party Docusaurus plugins on npm relying on this lifecycle.

Motivation

Introducing a new allContentLoaded({allContent, actions}) plugin lifecycle offers the opportunity for plugins to consume data coming from other plugins.

This means you can create a plugin aggregating data from multiple plugins/instances, and display that information on a single page. For example, you could use this to create your site homepage and display some docs-related and blog-related info.

If your plugin has both a contentLoaded and allContentLoaded lifecycles, the routes and global data created by both will be shallowly merged.

const plugin = () => ({
  name: "plugin-name",
  loadContent: () => ({val: 42})
  contentLoaded({ actions, content }) {
    actions.addRoute({
      path: "/path1",
      component: "Comp",
    });
    actions.setGlobalData({
      val1: content.val, 
      shared: content.val,
    });
  },
  allContentLoaded({ actions }) {
    actions.addRoute({
      path: "/path2",
      component: "Comp",
    });
    actions.setGlobalData({
      val2: content.val * 2, 
      shared: content.val * 2,
    });
  },
});

In this case the plugin will have:

• routes /path1 and /path2
• global data: {val1: 42, val2: 84, shared: 84}

---

Limitation: this new lifecycle does not permit to display data from one plugin inside another's page. You can aggregate data for a new brand-new standalone page (such as your homepage), but you cannot display blog posts on a doc page for example. We will try to enable that use case later. Note it remains possible to implement a workaround to extend existing plugins: #4138

Note: technically the existing contentLoaded already received the allContent, but it was a secret undocumented feature (only used by our debug plugin) that is now replaced by this brand-new lifecycle. I won't consider this as a breaking change.

An important motivation for this new lifecycle is also the optimization of the dev server (#9903), to provide fine-grained plugin reloads and to avoid wasting CPU/IO running uselessly expensive lifecycles such as contentLoaded just because they could eventually read the former allContent data.

Test Plan

unit tests + dogfood on the debug plugin

Test links

• Preview: https://deploy-preview-9931--docusaurus-2.netlify.app/
• Content: https://deploy-preview-9931--docusaurus-2.netlify.app/__docusaurus/debug/content/
• Global data: https://deploy-preview-9931--docusaurus-2.netlify.app/__docusaurus/debug/globalData/

Related issues/PRs

Unlocks further DX optimizations: #9903

Related discussions: #9922 (reply in thread)

The allContent data was added to the contentLoaded params as part of #3229

---

Example

Reading this PR it might be complex to understand how to aggregate data from multiple plugins on a single page.

Here's an example aggregating the blog posts of 2 separate blogs into a single page.

https://stackblitz.com/edit/github-agngt8?file=MyHomePage%2FMyHomePagePlugin.js,MyHomePage%2FMyHomePage.js,docusaurus.config.js

export default async function MyHomePagePlugin(context, options) {
  return {
    name: 'my-home-page-plugin',
    async allContentLoaded({ allContent, actions }) {

      // We aggregate the 2 blog lists into 1 here
      const allBlogs = allContent['docusaurus-plugin-content-blog'];
      const blog1 = allBlogs['blog1'];
      const blog2 = allBlogs['blog2'];
      const allBlogPosts = [...blog1.blogPosts, ...blog2.blogPosts];

      // We create the route for the homepage here
      actions.addRoute({
        path: '/',
        exact: true,
        component: '@site/MyHomePage/MyHomePage.js',
        modules: {
          // "allBlogPosts" is the name of the React props the component will receive
          allBlogPosts: await actions.createData(
            'allBlogPosts.json', // The file name doesn't matter, we'll simplify this soon
            JSON.stringify(allBlogPosts)
          ),
        },
      });
    },
  };
}

export default function Home(props) {
  // We receive the created module as a prop here
  const { allBlogPosts } = props;
  return (
      <main>
        <h2>All blog posts</h2>
        <ul>
          {allBlogPosts.map((blogPost, i) => (
            <li key={i}>{blogPost.metadata.title}</li>
          ))}
        </ul>
      </main>
  );
}

IMPORTANT: be sure to understand the limits of the current approach. You can create a brand new page on which you display data of multiple plugins, but you can't inject data on an existing page created by an existing plugin. For example it's not possible to show blog posts on a doc page, or to show docs versions on a blog post, because it's not your plugin that creates those pages.

The solution to this problem will be adding support for React Server Components, so that you can access allContent directly in your React render tree instead of having to create a plugin. Track #9089

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	5e64950
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65eb4e15c5c50e00080b5ce2
😎 Deploy Preview	https://deploy-preview-9931--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
/	🟠 60	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 56	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 74	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 68	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 64	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 69	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No change detected	-	Mar 8, 2024, 5:51 PM

[github-actions]

Size Change: 0 B

Total Size: 992 kB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	75.4 kB
website/build/assets/css/styles.********.css	114 kB
website/build/assets/js/main.********.js	765 kB
website/build/index.html	37.9 kB

_{compressed-size-action}