Sidebar

[LeviticusMB]

I just upgraded from [email protected] and [email protected] to [email protected] and [email protected].

The Docusaurus site have an automatic sidebar and I generate the Markdown files into the docs tree like this:

const typeDocConfig = {
  disableSources:  true,
  excludePrivate:  true,
  excludeInternal: true,
  watch:           typeof process !== 'undefined' && process.env.TYPEDOC_WATCH === 'true',
  readme:          'none',
}

const config = {
  ...
  plugins: [
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-core-api',
        out: 'sdk/typescript/core',
        entryPoints: [ '../TypeScript/Core/src/index.ts' ],
        tsconfig: '../TypeScript/Core/tsconfig.json',
        sidebar: {
          categoryLabel: 'Core API',
        },
      },
    ],
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-node-api',
        out: 'sdk/typescript/node',
        entryPoints: [ '../TypeScript/NodeJS/src/module.ts' ],
        tsconfig: '../TypeScript/NodeJS/tsconfig.json',
        sidebar: {
          categoryLabel: 'Node.js API',
        },
      },
    ],
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-web-api',
        out: 'sdk/typescript/web',
        entryPoints: [ '../TypeScript/Web/src/module.ts' ],
        tsconfig: '../TypeScript/Web/tsconfig.json',
        sidebar: {
          categoryLabel: 'Web API',
        },
      },
    ],
  ]
  ...

After upgrading, the categoryLabel is no longer recognized so instead of Web API I now have @onslip/onslip-360-web-api in the sidebar. Additionally, all sub-folders are rendered in lower case, which looks really ugly.

So to make the sidebar look the same as it used to be, I now have to dynamically patch it, like so:

function injectTypeDocSidebars(topItems: any) {
  topItems.find((item) => item.type === 'category' && item.label === 'SDKs')
    .items.find((item) => item.type === 'category' && item.label === 'TypeScript/JavaScript')
    .items = [
      { type: 'category', 'label': 'Core API',    link: { type: 'doc', id: 'sdk/typescript/core/index' }, items: require('./docs/sdk/typescript/core/typedoc-sidebar.cjs') },
      { type: 'category', 'label': 'Node.js API', link: { type: 'doc', id: 'sdk/typescript/node/index' }, items: require('./docs/sdk/typescript/node/typedoc-sidebar.cjs') },
      { type: 'category', 'label': 'Web API',     link: { type: 'doc', id: 'sdk/typescript/web/index' },  items: require('./docs/sdk/typescript/web/typedoc-sidebar.cjs')  },
  ];

  return topItems;
}

const config: Config = {
  ...
  plugins: [
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-core-api',
        out: 'docs/sdk/typescript/core',
        entryPoints: [ '../TypeScript/Core/src/index.ts' ],
        tsconfig: '../TypeScript/Core/tsconfig.json',
      } satisfies Partial<any | PluginOptions & TypeDocOptions>,
    ],
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-node-api',
        out: 'docs/sdk/typescript/node',
        entryPoints: [ '../TypeScript/NodeJS/src/module.ts' ],
        tsconfig: '../TypeScript/NodeJS/tsconfig.json',
      } satisfies Partial<PluginOptions & TypeDocOptions>,
    ],
    [
      'docusaurus-plugin-typedoc', {
        ...typeDocConfig,
        id: 'typescript-web-api',
        out: 'docs/sdk/typescript/web',
        entryPoints: [ '../TypeScript/Web/src/module.ts' ],
        tsconfig: '../TypeScript/Web/tsconfig.json',
      } satisfies Partial<PluginOptions & TypeDocOptions>,
    ],
  ],
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          sidebarItemsGenerator: async function({ defaultSidebarItemsGenerator, ...args }) {
            return injectTypeDocSidebars(await defaultSidebarItemsGenerator(args));
          },
        },
  ...

Which i find ugly and fragile.

Am I missing something?

[tgreyuk]

I wouldn't say that your are missing something. There will need to be some manual sidebar configuration, but the expectation would be that this would be configured directly in the sidebar file. However I assume your entire sidebar is currently auto-generated?

I take your point though, moving to a manual sidebar does create more effort but it is much easier to configure. I'll have a think if anything could be made a bit easier for your kind of setup.

[LeviticusMB]

Yup the entire sidebar is auto-generated and the TypeDocs are somewhere in the middle, a couple of levels in.