Guidance for doc versioning on specific parts of the site

[Devon-White]

Our platform provides many services and SDKs, so I was hoping to be able to versioned specific pages by declaring a docs plugin instance of just that docs directory.

However, im finding MDX compilation issues when attempting to render the docs. An error could look like:

Error: MDX compilation failed for file "C:\Users\devon\projects\docs\docs\sdks\reference\realtime-sdk\pubsub\pubsub-pubsubmessage.md"    
Cause: Unexpected `FunctionDeclaration` in code: only import/exports are supported
Details:
{
  "column": 1,
  "message": "Unexpected `FunctionDeclaration` in code: only import/exports are supported",
  "line": 39,
  "name": "39:1-145:2",
  "place": {
    "start": {
      "line": 39,
      "column": 1,
      "offset": 847
    },
    "end": {
      "line": 145,
      "column": 2,
      "offset": 4287
    }
  },
  "reason": "Unexpected `FunctionDeclaration` in code: only import/exports are supported",
  "ruleId": "non-esm",
  "source": "micromark-extension-mdxjs-esm",
  "url": "https://github.com/micromark/micromark-extension-mdxjs-esm#unexpected-type-in-code-only-importexports-are-supported"
}

When the contents is only:

---
title: "PubSubMessage"
---

Represents a message in a PubSub context.


## **Properties**

### channel

The channel in which this message was sent.

**Syntax:** `PubSubMessage.channel()`

**Returns:** `string`

---

### content

The content of this message.

**Syntax:** `PubSubMessage.content()`

**Returns:** `string`

---

### id

The id of this message.

**Syntax:** `PubSubMessage.id()`

**Returns:** `string`

---

### meta

Any metadata associated to this message.

**Syntax:** `PubSubMessage.meta()`

**Returns:** `any`

---

### publishedAt

The date and time at which this message was published.

**Syntax:** `PubSubMessage.publishedAt()`

**Returns:** `Date`

Test PR can be found at: signalwire/docs#319

In the preset config, we exclude the SDK path

    {
      docs: {
        editUrl: "https://github.com/signalwire/docs/edit/main/",
        path: "docs",
        routeBasePath: "/",
        exclude: [
          "**/sdks/reference/realtime-sdk/**", // Exclude real-time SDK docs - They are versioned
        ],
        sidebarPath: require.resolve("./sidebarsConfig"),
        docItemComponent: "@theme/ApiItem",
        sidebarItemsGenerator: sidebarGenerator,
        showLastUpdateTime: false,
        remarkPlugins: [
          [require("@docusaurus/remark-plugin-npm2yarn"), { sync: true }],
          [require("../plugins/remark-plugin-yaml-and-json"), { sync: false }],
          [require("../plugins/remark-plugin-vfile-reporter"), {}],
          [require("../plugins/remark-plugin-api-table"), {}]
        ],
        beforeDefaultRemarkPlugins: [
          // TODO: temporarily don't fail on a11y errors
          [require("../plugins/remark-plugin-a11y-checker"), { stopOnError: false }],
          [require("../plugins/remark-plugin-image-to-figure"), {}],
        ],
        tags: 'tags.yml',
        onInlineTags: 'throw'
      },
      blog: {
        blogSidebarCount: "ALL",
      },
      theme: {
        customCss: require.resolve("../src/css/index.scss"),
      },
      gtag: process.env.GTAG
        ? {
            trackingID: process.env.GTAG,
          }
        : undefined,
    } satisfies Options,

Then for our SDK docs plugin we define it like such:

import type { PluginConfig } from "@docusaurus/types";
import { Options } from "@docusaurus/plugin-content-docs";
import sidebarGenerator from "../../plugins/SidebarGenerator";


export const realtimeSdkPlugin: PluginConfig = [
  "@docusaurus/plugin-content-docs",
  {
    id: "realtime-sdk",
    path: "docs/sdks/reference/realtime-sdk",
    routeBasePath: "sdks/reference/realtime-sdk",
    sidebarPath: require.resolve("../sidebarsConfig/relay-realtime-sidebar.ts"),
    editUrl: "https://github.com/signalwire/docs/edit/main/",
    docItemComponent: "@theme/ApiItem",
    sidebarItemsGenerator: sidebarGenerator,
    remarkPlugins: [
      [require("@docusaurus/remark-plugin-npm2yarn"), { sync: true }],
      [require("../../plugins/remark-plugin-yaml-and-json"), { sync: false }],
      [require("../../plugins/remark-plugin-vfile-reporter"), {}],
      [require("../../plugins/remark-plugin-api-table"), {}]
    ],
    beforeDefaultRemarkPlugins: [
      // TODO: temporarily don't fail on a11y errors
      [require("../../plugins/remark-plugin-a11y-checker"), { stopOnError: false }],
      [require("../../plugins/remark-plugin-image-to-figure"), {}],
    ],
    versions: {
      current: {
        label: "v4 (Latest)",
      },
    },
  } satisfies Options,
];

Any idea what im doing incorrectly here?

[Devon-White]

I was able to solve this by pulling the docs out of the preset docs directory. Even though they were being excluded, it somehow behaves better when the versioned docs are in their standalone directory.

After doing that, I observed that the version drop down will still show on every doc (even if that specific doc isnt versioned).

So far i was able to solve this by swizzling the DocsVersionDropdownNavbarItem and adding the following logic:

import React from 'react';
import DocsVersionDropdownNavbarItem from '@theme-original/NavbarItem/DocsVersionDropdownNavbarItem';
import type DocsVersionDropdownNavbarItemType from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
import type {WrapperProps} from '@docusaurus/types';
import { useActivePlugin } from '@docusaurus/plugin-content-docs/client';

type Props = WrapperProps<typeof DocsVersionDropdownNavbarItemType>;

export default function DocsVersionDropdownNavbarItemWrapper(props: Props): JSX.Element | null {
  const { docsPluginId } = props;
  
  // Get the currently active docs plugin
  const activePlugin = useActivePlugin();
  
  // Only show the version dropdown if:
  // 1. We're currently on a docs page (activePlugin exists)
  // 2. The active plugin matches the dropdown's plugin ID
  // 3. The dropdown has a specific plugin ID (meaning it's for a non-preset plugin instance)
  const isOnMatchingPluginDocs = activePlugin?.pluginId === docsPluginId;
  const isPluginSpecificDropdown = docsPluginId && docsPluginId !== 'default';
  
  if (!activePlugin || !isOnMatchingPluginDocs || !isPluginSpecificDropdown) {
    return null;
  }
  
  return (
    <>
      <DocsVersionDropdownNavbarItem {...props} />
    </>
  );
}

So far it seems to be working as intended.

[slorber]

I have no idea what you are doing sorry 😅 Your PR is huge and your code samples show so many things at once that I have no idea what I should look at exactly.

But glad you solved it. If you need help, please create a minimal repro that focus only on your problem instead of showing complex but unrelated configs using third-party plugins we don't own.