multi-instance support with plugin-sitemap

[greenpau]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Failed to generate sitemap for multi-instance setup.

Steps to reproduce

Have multi-instance setup, then add the following plugin level config:

diff --git a/docusaurus.config.js b/docusaurus.config.js
index 63f742d..70884fb 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -39,7 +39,15 @@ const config = {
   ],

   plugins: [
-    require.resolve('@cmfcmf/docusaurus-search-local')
+    require.resolve('@cmfcmf/docusaurus-search-local'),
+    [
+      '@docusaurus/plugin-sitemap',
+      {
+        changefreq: 'weekly',
+        priority: 0.5,
+        // trailingSlash: false,
+      },
+    ],
   ],

   themeConfig:

Expected behavior

Sitemap generated for both instances of docs in multi-instance setup.

Actual behavior

Get error:

Unable to build website for locale "en".
Error: Plugin "docusaurus-plugin-sitemap" is used 2 times with id default.
To use the same plugin multiple times on a Docusaurus site, you need to assign a unique id to each plugin instance.
    at <omitted>/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:20:23
    at Array.forEach (<anonymous>)
    at <omitted>/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:18:45
    at Array.forEach (<anonymous>)
    at ensureUniquePluginInstanceIds (<omitted>/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:16:35)
    at initPlugins (<omitted>/node_modules/@docusaurus/core/lib/server/plugins/init.js:154:51)
    at loadPlugins (<omitted>/node_modules/@docusaurus/core/lib/server/plugins/index.js:56:40)
    at load (<omitted>/node_modules/@docusaurus/core/lib/server/index.js:186:113)
    at async buildLocale (<omitted>/node_modules/@docusaurus/core/lib/commands/build.js:83:19)
    at async tryToBuildLocale (<omitted>/node_modules/@docusaurus/core/lib/commands/build.js:35:20)
    at async mapAsyncSequencial (<omitted>/node_modules/@docusaurus/utils/lib/index.js:263:24)
    at async build (<omitted>/node_modules/@docusaurus/core/lib/commands/build.js:71:25)

Your environment

• Public source code: https://github.com/authp/authp.github.io
• Public site URL: https://authp.github.io
• Docusaurus version used: 2.0.0-beta.9
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node v14.17.6
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): CentOS 8

Reproducible demo

No response

Self-service

• I'd be willing to fix this bug myself.

[greenpau]

it looks like docs and blog got the multi-instance support in #3204, but not the sitemap plugin.

[greenpau]

The error is being triggered in node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:

            if (pluginInstancesWithId.length !== 1) {
                throw new Error(`Plugin "${pluginName}" is used ${pluginInstancesWithId.length} times with id ${pluginId}.\nTo use the same plugin multiple times on a Docusaurus site,    you need to assign a unique id to each plugin instance.`);
            }

🤔 how do you auto-assign IDs to a plugin you define only once by including it in plugins section of docusaurus.config.js? Need to look at plugin lifecycle. Specifically, where do they get initialized?

[greenpau]

Found a reference to the lifecycle in node_modules/@docusaurus/core/lib/server/plugins/index.js:

exports.sortConfig = sortConfig;
async function loadPlugins({ pluginConfigs, context, }) {
    // 1. Plugin Lifecycle - Initialization/Constructor.
    const plugins = (0, init_1.default)({
        pluginConfigs,
        context,
    });
    // 2. Plugin Lifecycle - loadContent.
    // Currently plugins run lifecycle methods in parallel and are not order-dependent.
    // We could change this in future if there are plugins which need to
    // run in certain order or depend on others for data.

I actually want to run a single instance of the plugin ... why do I get the message about multiple instances?

[greenpau]

Quick look at:

                console.log(pluginId);
                console.log(pluginInstancesWithId);

The output follows:

default
[
  {
    name: 'docusaurus-plugin-sitemap',
    postBuild: [AsyncFunction: postBuild],
    options: {
      changefreq: 'weekly',
      priority: 0.5,
      trailingSlash: false,
      id: 'default'
    },
    version: {
      type: 'package',
      name: '@docusaurus/plugin-sitemap',
      version: '2.0.0-beta.9'
    }
  },
  {
    name: 'docusaurus-plugin-sitemap',
    postBuild: [AsyncFunction: postBuild],
    options: {
      changefreq: 'weekly',
      priority: 0.5,
      trailingSlash: false,
      id: 'default'
    },
    version: {
      type: 'package',
      name: '@docusaurus/plugin-sitemap',
      version: '2.0.0-beta.9'
    }
  }
]

The two instances are the same.

The next step is finding out how do they get added to the list of plugins? Then, eliminate the duplication.

[greenpau]

The plugin normalization happens in node_modules/@docusaurus/core/lib/server/plugins/init.js as part of initPlugins().

[greenpau]

Disabled the ensureUniquePluginInstanceIds check and added some console messages to see what is in pluginConfig:

        console.log("PLUGIN_CONFIG");
        console.log(pluginConfig);

// (0, pluginIds_1.ensureUniquePluginInstanceIds)(plugins);

For the first int

PLUGIN_CONFIG
<omitted>/node_modules/@docusaurus/plugin-sitemap/lib/index.js

and the second is:

PLUGIN_CONFIG
[
  '@docusaurus/plugin-sitemap',
  { changefreq: 'weekly', priority: 0.5, trailingSlash: false }
]

Note: The node_modules/@cmfcmf/docusaurus-search-local/lib/server/index.js works find in the multi-instance environment. I wonder what is different in its lifecycle management?

[greenpau]

Two issues:

1. Limit the number of instance of sitemap plugins to 1
2. Modify the function to recognize multi-instance.

docusaurus/packages/docusaurus-plugin-sitemap/src/index.ts

Lines 30 to 34 in cbcaa52

	const generatedSitemap = await createSitemap(
	siteConfig,
	routesPaths,
	options,
	);

Added debug and the routesPaths contain the paths from both instances.

[greenpau]

Kept the ensureUniquePluginInstanceIds check disabled and my sitemap.xml got generated successfully 😃 Home stretch ⚾

[Josh-Cena]

Thanks for investing your own time to look into this:D

I'm not sure I understand what you are looking for. Are you trying to use multiple sitemap plugins? For what purpose? Beware that preset-classic already comes with a sitemap so usually just configuring it through the preset is sufficient.

[greenpau]

I'm not sure I understand what you are looking for. Are you trying to use multiple sitemap plugins? For what purpose?

@Josh-Cena , I am trying to generate a single sitemap.xml. Through the troubleshooting, I was able doing so. See https://authp.github.io/sitemap.xml

However, if a website has multiple doc sections, i.e. multi-instance (see here), then the plugin fails, because based on what I observe each doc section would trigger the addition of a new sitemap plugin. Both would have the default id, and therefore the ensureUniquePluginInstanceIds fails and errors get triggered.

Beware that preset-classic already comes with a sitemap so usually just configuring it through the preset is sufficient.

I think it does not happen by default.

[Josh-Cena]

WDYM, does not happen by default? https://docusaurus.io/docs/next/presets#docusauruspreset-classic

[Josh-Cena]

what I observe each doc section would trigger the addition of a new sitemap plugin

That's false. A plugin never summons or even knows about another plugin. Your problem is that you did't put the configuration in the right place. I'll see what we can do to help users prevent these kinds of mistakes as they happen often