Difficulties extending configureWebpack function of @docusaurus/plugin-content-docs

[SheezZarR]

Hello! I want to add a few webpack plugins to the base docs plugin that I want to use for my docusaurus instance.

I decided to go the route of using the base plugin and then extending some of the functions but that had proven to be cumbersome. I found issues #4138 and #3299 which listed ways to do what I had in mind. However I had been getting weird errors which were hard to comprehend.

First one was

> my-website@0.0.0 start
> docusaurus start


    -------------------------------------------------------------------------------------------------------------------------------------------- 
                                                                                                                                                 
                                                          Update available 3.9.2 → 3.10.1                                                        
                                                                                                                                                 
                                 To upgrade Docusaurus packages with the latest version, run the following command:                              
        `npm i @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest @docusaurus/tsconfig@latest      
                                                             @docusaurus/types@latest`                                                           
                                                                                                                                                 
    -------------------------------------------------------------------------------------------------------------------------------------------- 

[INFO] Starting the development server...

[ERROR] Error: It is not possible to use docs without any version. No version is included because you have requested to not include /home/dev/Dev/Docusaurus/my-website/docs through "includeCurrentVersion: false", while the versions file is empty/non-existent.
    at readVersionNames (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/plugin-content-docs/lib/versions/files.js:105:15)
    at async readVersionsMetadata (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/plugin-content-docs/lib/versions/version.js:160:29)
    at async pluginContentDocs (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/plugin-content-docs/lib/index.js:51:30)
    at async Object.extendedDocsPlugin [as plugin] (/home/dev/Dev/Docusaurus/my-website/src/plugins/extended-docs/index.ts:18:26)
    at async initializePlugin (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:91:32)
    at async Promise.all (index 6)
    at async initPluginsConfigs (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:118:22)
    at async initPlugins (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:128:39)
    at async /home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/plugins.js:143:36
    at async loadSite (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/site.js:155:45)
    at async createReloadableSite (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/start/utils.js:62:16)
    at async doStart (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/start/start.js:22:28)
    at async Promise.all (index 0)
    at async runCLI (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/cli.js:56:5)
    at async file:///home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3
[INFO] Docusaurus version: 3.9.2
Node version: v22.22.2

The second one.
(after I add versions: {current: {path: ''}} and includeCurrentVersion: true to docusaurus.config.ts.

> my-website@0.0.0 start
> docusaurus start


    -------------------------------------------------------------------------------------------------------------------------------------------- 
                                                                                                                                                 
                                                          Update available 3.9.2 → 3.10.1                                                        
                                                                                                                                                 
                                 To upgrade Docusaurus packages with the latest version, run the following command:                              
        `npm i @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest @docusaurus/tsconfig@latest      
                                                             @docusaurus/types@latest`                                                           
                                                                                                                                                 
    -------------------------------------------------------------------------------------------------------------------------------------------- 

[INFO] Starting the development server...

[ERROR] TypeError: Url must be a string. Received undefined
    at normalizeUrl (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/utils/lib/urlUtils.js:65:19)
    at createVersionMetadata (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/plugin-content-docs/lib/versions/version.js:133:44)
    at async Promise.all (index 0)
    at async pluginContentDocs (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/plugin-content-docs/lib/index.js:51:30)
    at async Object.extendedDocsPlugin [as plugin] (/home/dev/Dev/Docusaurus/my-website/src/plugins/extended-docs/index.ts:18:26)
    at async initializePlugin (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:91:32)
    at async Promise.all (index 6)
    at async initPluginsConfigs (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:118:22)
    at async initPlugins (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/init.js:128:39)
    at async /home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/plugins/plugins.js:143:36
    at async loadSite (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/server/site.js:155:45)
    at async createReloadableSite (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/start/utils.js:62:16)
    at async doStart (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/start/start.js:22:28)
    at async Promise.all (index 0)
    at async runCLI (/home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/lib/commands/cli.js:56:5)
    at async file:///home/dev/Dev/Docusaurus/my-website/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3
[INFO] Docusaurus version: 3.9.2
Node version: v22.22.2

I have spun up a repository for you to check what I am doing wrong in the configuration. Maybe I lack proper Javascript knowledge???

You can find the plugin I have setup at src/plugins/extended-docs/index.ts. There is nothing special there. just outputs the regular docs plugin back (from my perspective)... In docusaurus.config.ts, residing withing the root directory of the project, you can find the preset for docs looking like docs: false and then there is a plugin usage in plugins section.

Does preset setup of docusaurus collide with plugin implementation? Does preset configuration provide some defaults which I am missing in my example??

[slorber]

The problem is likely because you forgot this line:

export { validateOptions } from '@docusaurus/plugin-content-docs';

This is important because if you don't "forward" that method to your own plugin, the options never get "normalized", which means the default values the docs plugin expects remain undefined, leading to unexpected behaviors.

[SheezZarR]

Thanks a lot for helping me out!! Validate options did the trick. I was somewhat stuck on the "name" property in the my overwritten plugin. There is another catch that I have encountered.

Do I have to keep it as it is in the plugin instance and do not change anything? I have navbar item type: docSidebar and that rename caused docusaurus to build with failures showing other bizarre error messages. Do I have to fiddle with the navbar logic so it accepts my alternatively named docs plugin? Or how does it work?

[slorber]

I don't know what error you encountered and the associated code, so it's hard to tell 😅

[SheezZarR]

Ah.. Sorry about not sharing the exact error message. Thought the text description would be fine.

Here is the exact problem that I get:

The compilation steps are fine but once the docusaurus opens up in the browser I see the report.

Here is the complete code of the edited docusaurus plugin.

import { Plugin, LoadContext } from '@docusaurus/types';
import originalPluginPkg, {
  Options as DocsOptions,
} from '@docusaurus/plugin-content-docs';

export { validateOptions } from '@docusaurus/plugin-content-docs';

export default async function extendedDocsPlugin(
  context: LoadContext,
  options: DocsOptions,
): Promise<Plugin<any>> {
  const pluginInstance = await originalPluginPkg(context, options);

  return {
    ...pluginInstance,
    name: 'my-plug',
  };
}

I figured out one thing - by not overwriting the name I could get the thing working.

[slorber]

Yeah, that's because navbar items expect "global data" for a plugin named docusaurus-plugin-content-docs to be available. Not convenient but I don't have a better workaround to suggest.