Is it possible to generate sidebars programatically?

[ilg-ul]

I have several static arrays of names and links which I use in a page to generate lists of external links (one list per array).

I would like to also have these lists available in a sidebar with corresponding category entries, one for each array, something like this:

I tried to override the definitions in sidebar.ts with some code in docusaurus.config.ts, but it did not work; I was able to import and access the sidebars, but writing the items properties did not change the content of the sidebars.

For now I fully re-defined the links in the sidebar.ts, but I'm not very keen of using duplicate code.

Is there any way to generate this sidebar dynamically from the available static arrays, in docusaurus.config.ts, before anything else happens?

[ilg-ul]

@slorber, any thought on this?

[ilg-ul]

It's preferable that sidebars.ts doesn't import anything from the config file for coupling reasons.

I'm open to any suggestions.

You'd better move your static arrays to a standalone json file and import it from both config and sidebar files.

I already have a src/libs/tools.ts file with the list of tools:

export default function tools() {
    return {
        /* When updated, don't forget to add sitemap to robots.txt! */
        mainTools: [
            {
                appName: 'GNU AArch64 Embedded GCC',
                appLcName: 'aarch64-none-elf-gcc'
            },
            {
                appName: 'GNU Arm Embedded GCC',
                appLcName: 'arm-none-eabi-gcc'
            },
            {
                appName: 'LLVM clang',
                appLcName: 'clang'
            },
            {
                appName: 'CMake',
                appLcName: 'cmake'
            },
            {
                appName: 'GCC',
                appLcName: 'gcc'
            },
            {
                appName: 'Meson Build',
                appLcName: 'meson-build'
            },
            {
                appName: 'MinGW-w64 GCC',
                appLcName: 'mingw-w64-gcc'
            },
            {
                appName: 'Ninja Build',
                appLcName: 'ninja-build'
            },
            {
                appName: 'OpenOCD',
                appLcName: 'openocd'
            },
            {
                appName: 'QEMU Arm',
                appLcName: 'qemu-arm'
            },
            {
                appName: 'QEMU RISC-V',
                appLcName: 'qemu-riscv'
            },
            {
                appName: 'GNU RISC-V Embedded GCC',
                appLcName: 'riscv-none-elf-gcc'
            },
            {
                appName: 'Windows Build Tools',
                appLcName: 'windows-build-tools'
            },
        ],

        /* When updated, don't forget to add sitemap to robots.txt! */
        supplementaryTools: [
            {
                appName: 'GNU bison',
                appLcName: 'bison'
            },
            {
                appName: 'flex',
                appLcName: 'flex'
            },
            {
                appName: 'GNU m4',
                appLcName: 'm4'
            },
            {
                appName: 'NixOS PatchELF',
                appLcName: 'patchelf'
            },
            {
                appName: 'pkg-config',
                appLcName: 'pkg-config'
            },
            {
                appName: 'GNU realpath',
                appLcName: 'realpath'
            },
            {
                appName: 'GNU sed',
                appLcName: 'sed'
            },
            {
                appName: 'WineHQ',
                appLcName: 'wine'
            },
        ],

        workInProgressTools: [
            {
                appName: 'GNU Bash',
                appLcName: 'bash'
            },
            {
                appName: 'GNU texinfo',
                appLcName: 'texinfo'
            },
        ]
    }
}

And I also have a component which renders the lists:

import clsx from 'clsx';
import Heading from '@theme/Heading';
import styles from './styles.module.css';

import Link from '@docusaurus/Link';

import tools from '@site/src/libs/tools';

function Tool({ appName, appLcName }) {
  return (
      <div className="padding-vert--sm">
        <div>
          <b><Link to={'https://xpack-dev-tools.github.io/' + appLcName + '-xpack/'}>{appLcName}</Link></b> - <b>xPack {appName}</b>
        </div>
        <div className="padding-top--xs">
          <Link to={'https://github.com/xpack-dev-tools/' + appLcName + '-xpack/releases/'}><img alt="GitHub Release" src={'https://img.shields.io/github/v/release/xpack-dev-tools/' + appLcName + '-xpack'} /></Link>
          &nbsp;<Link to={'https://github.com/xpack-dev-tools/' + appLcName + '-xpack/releases/'}><img alt="GitHub Release Date" src={'https://img.shields.io/github/release-date/xpack-dev-tools/' + appLcName + '-xpack?label=date&color=YellowGreen'} /></Link>
          &nbsp;<Link to={'https://github.com/xpack-dev-tools/' + appLcName + '-xpack/releases/'}><img alt="GitHub Downloads (all assets, all releases)" src={'https://img.shields.io/github/downloads/xpack-dev-tools/' + appLcName + '-xpack/total.svg'} /></Link>
          &nbsp;<Link to={'https://github.com/xpack-dev-tools/' + appLcName + '-xpack/'}><img alt="GitHub Repo stars" src={'https://img.shields.io/github/stars/xpack-dev-tools/' + appLcName + '-xpack'} /></Link>
        </div>
      </div>
  )
}

function ToolWork({ appName, appLcName }) {
  return (
      <div>
        <b><Link to={'https://xpack-dev-tools.github.io/' + appLcName + '-xpack/'}>{appLcName}</Link></b> - <b>xPack {appName}</b>
      </div>
  )
}

function ToolsLeft() {
  return (
    <div className={clsx('col col--6')}>
      <div className="text--center padding-horiz--md padding-vert--lg">
        <Heading as="h2">Main Tools</Heading>
        {tools().mainTools.map((props, idx) => (
          <Tool {...props} />
        ))}
      </div>
    </div>
  );
}

function ToolsRight() {
  return (
    <div className={clsx('col col--6')}>
      <div className="text--center padding-horiz--md padding-vert--lg">
        <Heading as="h2">Supplementary Tools</Heading>
        {tools().supplementaryTools.map((props, idx) => (
          <Tool {...props} />
        ))}
      </div>
      <hr className="hero__hr2" />
      <div className="text--center padding-horiz--md padding-vert--md">
        <Heading as="h2">Work in Progress</Heading>
        {tools().workInProgressTools.map((props, idx) => (
          <ToolWork {...props} />
        ))}
      </div>
      <hr className="hero__hr2" />
      <div className="text--center padding-horiz--md padding-vert--md">
        <Heading as="h2">Internal</Heading>
        <b><Link to={'https://github.com/xpack-dev-tools/xbb-helper-xpack'}>xbb-helper</Link></b> - <b>xPack Build Helper</b>
      </div>
    </div>
  );
}

export default function HomepageTools(): JSX.Element {
  return (
    <section className={styles.features}>
      <div className="container">
        <div className="row padding-bottom--lg">
          <ToolsLeft key={0} />
          <ToolsRight key={1} />
        </div>
      </div>
    </section>
  );
}

This works fine, no problem with it.

---

Then I have a (currently unused) function in src/libs/addToolsToSidebar.ts that generates the sidebars:

import logger from '@docusaurus/logger';

import tools from './tools';

export default function addToolsToSidebar(sidebars) {
  for (const entry of sidebars.toolsSidebar) {
    if (entry.type === 'category') {
      if (entry.label === 'Main Tools') {
        logger.info(entry.label)
        entry.items = tools().mainTools.map((tool) => {
          logger.info('  ' + tool.appName)
          return {
            type: 'link',
            label: `xPack ${tool.appName}`,
            href: `https://xpack-dev-tools.github.io/${tool.appLcName}-xpack/`
          }
        })
      } else if (entry.label === 'Supplementary Tools') {
        logger.info(entry.label)
        entry.items = tools().supplementaryTools.map((tool) => {
          logger.info('  ' + tool.appName)
          return {
            type: 'link',
            label: `xPack ${tool.appName}`,
            href: `https://xpack-dev-tools.github.io/${tool.appLcName}-xpack/`
          }
        })
      }
    }
  }
}

I can call it at the beginning of docusaurus.config.ts with an input toolsSidebar with empty items arrays, and it fills them, but I don't know how to pass the resulting sidebar to docusaurus.

[slorber]

I don't know what you are doing, please provide a minimal/simplified repro example, not with real code, not a full complex site.

Sidebars are docs-specific and are not declared in the config file.
You can import ./path/toolsSidebar.json in website/sidebars.ts

Instead of writing code that "modifies" an existing sidebar, maybe you should write code that "generates" the sidebar (or a sidebar slice)

If tools always gives the same data, there's no reason for it to be a function and call it multiple times. Just use a JSON file or static exported object if need TS type inference (in this case, use as const)

[ilg-ul]

I don't know what you are doing

What is wrong with the post tile? Programatically means by running a piece of code, in Docusaurus case most probably at build time.

provide a minimal/simplified repro

• https://codesandbox.io/p/devbox/busy-snow-8nf3tq?workspaceId=b4be4eeb-bc42-4d95-a0c9-32536dcf644d

I want the sidebar in the docs/tools page to replicate the main page list of tools, without having to manually redefine the entries, but reuse the definitions in src/libs/tools.js.

Sidebars are docs-specific and are not declared in the config file.

I don't want to define them in the config file, the config file was considered as a possible location where to run the code that generates the sidebar during build time.

You can import ./path/toolsSidebar.json in website/sidebars.ts

The list of tools is not in such a json, it is in an array of names. (well, now it is, because I manually redefined it as a duplicate)

Instead of writing code that "modifies" an existing sidebar, maybe you should write code that "generates" the sidebar (or a sidebar slice)

Sure, I can write a function to return whatever you want, but the question remains the same, where do I call this function, and how do I pass the result to Docusaurus.

If tools always gives the same data, there's no reason for it to be a function

The list of tools will grow with time; I want to add the new definitions in a single place, and both the list in the home page and the sidebar to be automatically updated.

A workaround would probably be to manually define the tools in the sidebar object, then read it in the main page and do some string juggling to extract the name and link from there, but this is an ugly kludge.

[slorber]

The list of tools is not in such a json, it is in an array of names. (well, now it is, because I manually redefined it as a duplicate)

An array of name or a JSON, it's the same, you can import both from any js or ts file.

The advice remain: import your tools in sidebars.js

You can keep a function if you want, or export a static object, or rename the file as json. It doesn't matter. What matters is that sidebars.js use the data you already define instead of duplicating it.

but the question remains the same, where do I call this function, and how do I pass the result to Docusaurus.

The answer remains the same,

If it's a function, you import it in sidebars.js and call it there, take the result to create sidebar items.

The only subtle thing to understand is that @site is a client-side only alias that is only available in bundled code (meant to run in your browser), you can't use it to import anything on the Node.js side like sidebars and configs.

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

import tools from './src/libs/tools';

const toolsItems = tools().mainTools.map((tool) => {
  return {
    type: 'link',
    label: tool.appName,
    href: 'https://xpack-dev-tools.github.io/' +tool.appLcName,
  }
})

const sidebars: SidebarsConfig = {
  toolsSidebar: [
    {
      type: 'doc',
      label: 'Tools',
      id: 'tools/index'
    },
    {
      type: 'category',
      label: 'Main Tools',
      collapsed: false,
      items: toolsItems
    },
  ]
};

export default sidebars;

[ilg-ul]

If it's a function, you import it in sidebars.js and call it there, take the result to create sidebar items.

The only subtle thing to understand is that @site is a client-side only alias that is only available in bundled code (meant to run in your browser), you can't use it to import anything on the Node.js side like sidebars and configs.

Ah, I think I get it now, you suggest to move everything from build time to client-side.

I moved everything to the top folder, and the result is:

sidebar.ts:

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
import toolsSidebar from './sidebars-tools.js';

const sidebars: SidebarsConfig = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

  // But you can create a sidebar manually
  docsSidebar: [
    {
      type: 'doc',
      id: 'getting-started/index',
      label: 'Getting Started'
    },
    {
      type: 'doc',
      id: 'about/index',
      label: 'About'
    },
  ],
  toolsSidebar,
};

export default sidebars;

sidebar-tools.ts:

import type {SidebarConfig} from '@docusaurus/plugin-content-docs';

import appTools from './tools'

function itemsOf(tools) {
  return tools.map((tool) => {
    return {
      type: 'link',
      label: tool.appName,
      href: 'https://xpack-dev-tools.github.io/' + tool.appLcName,
    }
  })
}

const toolsSidebar: SidebarConfig = [
    {
      type: 'doc',
      label: 'Tools',
      id: 'tools/index'
    },
    {
      type: 'category',
      label: 'Main Tools',
      collapsed: false,
      items: itemsOf(appTools.mainTools)
    },
    {
      type: 'category',
      label: 'Supplementary Tools',
      collapsed: true,
      items: itemsOf(appTools.supplementaryTools)
    },
  ]
;

export default toolsSidebar;

and tools.ts:

const tools = {
    mainTools: [ /* ... */ ],
    supplementaryTools: [ /* ... */ ],
}

export default tools;

Is this acceptable? I'm generally reticent to add code to client-side, since I don't know the side effects, but this one seems harmless.

[slorber]

Ah, I think I get it now, you suggest to move everything from build time to client-side.

I don't know what you mean. This is not what I suggest.

tools.js is not client, nor Node. It can be both. What makes something client-side is importing it in client-side code.

docusaurus.config.js and sidebars.js are Node-side, not client-side.

You can import tools.js in pages/index.js: it will be bundled and run in client-side

You can import tools.js in sidebars.js: it will run Node-side

If your file is imported from both places, it has to support both envs. It can't use any Node-only API, nor any browser-only API. It has to limit itself to the common subset of features both envs support.

[ilg-ul]

docusaurus.config.js and sidebars.js are Node-side, not client-side.

Perhaps adding a clear comment in all files that are Node-side would make things more easy to grasp and reduce support requests.

Thank you for your help, I think we can close this now.

[slorber]

#10608