When configured for versioning, I can't use an outputDir outside the docs plugin's path

[ElliotFriend]

Describe the bug

If my configured versions in the docusaurus-plugin-openapi-docs plugin instance specify an outputDir that does not contain the path value from the @docusaurus/plugin-content-docs plugin instance, then gen-api-docs:version will fail to build.

Expected behavior

For the docusaurus-plugin-openapi-docs plugin to generate the versioned MDX files at whatever location I have configured. Even if it's outside the docs path.

Current behavior

I think the docusaurus-plugin-openapi-docs plugin assumes that the outputDir for a given version will always be contained within the path value for the docs plugin.

Trying to generate the versioned MDX files like yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4 results in an error similar to:

[ERROR] TypeError: Cannot read properties of undefined (reading 'replace')
    at /Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:256:30
    at Array.map (<anonymous>)
    at generateApiDocs (/Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:225:17)
    at async Command.<anonymous> (/Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:535:11)

(Note: those line numbers are probably wrong, I had added some console.log() statements in that file for troubleshooting)

Possible solution

One possible fix might be as simple as modifying the plugin's index.ts file like this:

          if (docRouteBasePath) {
-           infoBasePath = `${docRouteBasePath}/${outputDir
-             .split(docPath!)[1]
-             .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+           infoBasePath = outputDir.indexOf(docPath) > -1
+             ? `${docRouteBasePath}/${outputDir
+                 .split(docPath)[1]
+                 replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "")
+             : infoBasePath;
          }

If that's a fitting fix, I'm more than happy to create a PR for it. (Here's a patch I'm using temporarily to fix it and it's working pretty well I think [ignore the other stuff in the patch file, that's an unrelated issue that I'll someday make a PR for lol])

Steps to reproduce

Here's the steps I remember doing:

1. Create a new version with the docusaurus docs plugin using yarn docusaurus docs:version:ap 2.8.4 (ap is the id of the docs plugin instance)

2. Add versions to the openapi plugin so it can re-generate the "old" versions when required. Including the plugin-content-docs instance here, for (hopefully) added clarity.

[
    "docusaurus-plugin-openapi-docs",
    {
        id: "ap-apis",
        docsPluginId: 'ap',
        config: {
            ap_platform: {
                specPath: "openapi/anchor-platform/bundled-platform.yaml",
                outputDir: "platforms/anchor-platform/api-reference/platform/transactions",
                hideSendButton: true,
                template: "src/template.mustache",
                version: "3.0.0",
                label: "v3.0.0",
                baseUrl: '/platforms/anchor-platform/next/api-reference/platform/transactions',
                versions: {
                    "2.8.4": {
                        specPath: "openapi/anchor-platform/versions/platform-2.8.4.yaml",
                        outputDir: "ap_versioned_docs/version-2.8.4/api-reference/platform/transactions",
                        label: "v2.8.4",
                        baseUrl: "/platforms/anchor-platform/api-reference/platform/transactions"
                    }
                }
            } satisfies OpenApiPlugin.Options,
        }
    }
],
[
    "@docusaurus/plugin-content-docs",
    {
        id: "ap",
        path: "platforms/anchor-platform",
        routeBasePath: "/platforms/anchor-platform",
        docItemComponent: "@theme/ApiItem",
        sidebarPath: "config/anchorPlatform.sidebar.ts",
        editUrl: "https://github.com/stellar/stellar-docs/tree/main",
        exclude: ['**/component/**', '**/README.md'],
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
    },
],

4. Attempt to change and re-generate the MDX files with yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4
5. Error as described above.

Context

My use-case is a little complicated here, and likely atypical. We're configuring a new instance of @docusaurus/plugin-content-docs (there are others) to work with a new instance of docusaurus-plugin-openapi-docs (there are also others). We want to setup versioning for just a specific part of our docs site, hence the multi-instance stuff.

We want to version all of the docs that are managed by this @docusaurus/plugin-content-docs instance. So, I've used the "regular" docusaurus method to make a new version. When configuring the docusaurus-plugin-openapi-docs instance, I'm adding versions so that I could update the "old" versions if it ever becomes necessary.

Maybe this isn't the "best" or "typical" way of accomplishing this? Essentially we're looking to version everything under a /certain/url/path without versioning anything else. Is there already any established precedent for this kind of use-case?

The relevant config in the working branch can be found here, for those curious enough to dive in.

Your Environment

• Version used: 3.0.1
• Environment name and version: node.js v20
• Operating System and version: macOS 14.5
• Link to your project: The feature branch is located here https://github.com/stellar/stellar-docs/tree/ap/versioning-setup

[sserrata]

Hi @ElliotFriend, this is expected behavior as the path is derived by docsPluginId at the root/parent level, meaning it's designed to be "inherited" by versions.

Have you considered/tried separating versions into their own docusaurus-plugin-openapi-docs instances?

Note that I've not thoroughly tested multi plugin instances so I make no guarantees it will work 😅