How to extend the blog contentLoaded() ?

[ilg-ul]

I'm trying to find a way to add some actions after the blog contentLoaded() function is executed, in order to create some global data to be used in custom pages (like my chronology table displayed in the home page).

From #4138 (comment) I understood that one possible suggestion is to create a new plug-in based on the existing plug-in, and to rewrite the contentLoaded() function to first call the original contentLoaded() then do the custom actions. There were also several discussions related to some middleware, but it is not clear if any were implemented.

Is this still the best solution available in 3.1?

I'm also wandering why not extend the plug-in loader, and call a hook (like afterContentLoaded(), with the same arguments), if available in the plug-in configuration?

[slorber]

The workaround I suggest is still something you can use today, and nothing was implemented so far.

I'm also wandering why not extend the plug-in loader, and call a hook (like afterContentLoaded(), with the same arguments), if available in the plug-in configuration?

If we do that, we'd have to do beforeContentLoaded too, because it actually makes sense to do things before loading content, such as downloading markdown files from a CMS.

To me an API such as this one is more flexible, supports both use cases at the same time, and in sync with other API designs we already have. And you can more easily parallelize work instead of executing your code/our code sequentially.

async function loadContent(params) {
  console.log('before');
  const content = params.defaultLoadContent(params);
  console.log('after');
  return content;
},

---

I'm also wandering why not extend the plug-in loader

This is already what is suggested in the other issue, so this idea is not really new.

What we need is someone to invest time and design a proper API for that feature.

It doesn't make sense to let users only extend this hook.

All plugins support this hook and many more hooks, so what kind of generic API could we create to enable users to extend all hooks.

• Should we pass an extra config object to the plugin declaration?
• Should we pass lifecycle hooks as regular plugin options?
• And then how would all this work with preset plugins?

Those are the questions to answer if we want to make progress on this

[ilg-ul]

we'd have to do beforeContentLoaded too ... downloading markdown files from a CMS

Isn't downloading content the responsibility of loadContent(), thus better placed in a hook called afterLoadContent()?

Otherwise, for a fully general solution, pairs of before/after hooks should cover all possible cases.

someone to invest time and design a proper API for that feature

I don't know the current API well enough to design something from scratch, but perhaps I can comment on different proposals, and try to validate them with my projects.

For my use case (apart from the chronology site I have many other separate sites that I have to migrate from Jekyll), until there will be a better solution, I was planning to make a fork and add an afterContentLoaded() function to the blog plug-in configuration.

what kind of generic API could we create to enable users to extend all hooks

Good question. The lifestyle API does not seem very complex, and I'm not sure all functions really need before/after hooks. Anyways, I wouldn't mind to pass them as regular plugin options, they'll most probably be implemented in separate files and the imported functions passes to the plugin.

If there are other functions apart from the Lifecycle API, they must be identified first, I have no idea about them.

If in the end we get too many functions, probably it makes sense to group them somehow, for example as config.lifeCycleHooks.afterContentLoaded().

As a general idea, in the C++ world I come from, designs are object oriented, and the concept of hooks or callbacks is not really necessary, if you need to enhance the functionality of an object, you derive from it and reimplement a method. I used the same object oriented design in my TypeScript CLI projects and had no problems with it.

Docusaurus takes a different approach, more JavaScript specific and less structured by my taste, and extending things seems more difficult.

[slorber]

Isn't downloading content the responsibility of loadContent(), thus better placed in a hook called afterLoadContent()?

No, loading content is usually reading md files on the filesystem and creating an in-memory representation of this content.

Before doing that, the files must exist on the filesystem, so if you need to download them you'd have to do it before reading them.

If there are other functions apart from the Lifecycle API, they must be identified first, I have no idea about them.

Other functions are plugin-specific and can be added as regular plugin options. For example the blog plugin will have a sortPosts hook: #9840 (and that doesn't make sense for the docs plugin to have it)

If in the end we get too many functions, probably it makes sense to group them somehow, for example as config.lifeCycleHooks.afterContentLoaded().

That could be a solution, but then this hook would be called for each plugin, so it needs to receive the plugin name/id as part of its API.

You probably don't want to run the same logic for blog content loading vs docs content loading, if your site has support for both.

As a general idea, in the C++ world I come from, designs are object oriented, and the concept of hooks or callbacks is not really necessary, if you need to enhance the functionality of an object, you derive from it and reimplement a method. I used the same object oriented design in my TypeScript CLI projects and had no problems with it.

Docusaurus takes a different approach, more JavaScript specific and less structured by my taste, and extending things seems more difficult.

I also come from an object-oriented world and did a lot of Java 15 years ago.

We use regular JS objects instead of classes for our plugins, but really is there even a big difference between those 2 things?

async function loadContent(params) {
  console.log('before');
  const content = params.defaultLoadContent(params);
  console.log('after');
  return content;
}

class CustomBlogPlugin extends BlogPlugin {
  async function loadContent(params) {
    console.log('before');
    const content = super.loadContent(params);
    console.log('after');
    return content;
  },
}

🤷‍♂️ this leads to the same outcome

I'm not against migrating to a class-based approach though, it might be easier and more intuitive to extend for those used to OOP.

We'll have to study if doing this change would be a break change or not.

--

Also something important to consider: we are not the only one creating plugins. Our community create plugins too, and currently may not use ES classes. So this means that if this is the approach we adopt, all plugin authors would have to use classes if they want to support the ability to extend.

[ilg-ul]

config.lifeCycleHooks.afterContentLoaded().
That could be a solution, but then this hook would be called for each plugin, so it needs to receive the plugin name/id as part of its API.

Ah, sorry for the misunderstanding, by config I don't mean the global configuration, I mean the plugin configuration; for example, in my multi-blog use case, only one blog instance needs such extra functionality.

In practical terms, for my use case, I would patch loadPlugins() in packages/docusaurus/src/server/plugins/index.ts:

      await plugin.contentLoaded({content, actions, allContent});

      if (plugin.afterContentLoaded) {
        await plugin.afterContentLoaded({content, actions, allContent});
      }

this leads to the same outcome

Yes, but the second one is generic and can be used for any class method, while the first one is specific for that use case, and requires additional default functions passed via the params.

Our community create plugins too, and currently may not use ES classes.

I use classes in all my TS projects, so my vote definitely goes for ES classes, but it is up to you to decide on this issue.

Till then I'll use the above hack in my fork and wait for your solution. There isn't much I have to do, just to prepare an array of records for the chronology table displayed in the site home page.