Versioned navbar item link to generated index

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I’m using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

We currently have 3 navbar links we would like to support versioning in. They all use to: '...' nowadays, which always points to the latest stable version and ignores the currently selected one. I know we can use type: 'doc' with doc id to have a versioned link, but I dont see a way to do this for a generated index page.

I can try to provide minimal repro if needed, but it would take a bit more time as I would have to setup versioned content, so giving you our production site instead for now.

Reproducible demo

https://github.com/apify/crawlee/tree/master/website

Steps to reproduce

Try to change the “examples” navbar item to use type: 'doc' in the config:

{
    type: 'doc',
    docId: 'examples',
    label: 'Examples',
    position: 'left',
},

Examples are defined in sidebars.js as generated-index type:

{
    type: 'category',
    label: 'Examples',
    link: {
        type: 'generated-index',
        title: 'Examples',
        slug: '/examples',
        keywords: ['examples'],
    },
    items: [
        {
            type: 'autogenerated',
            dirName: 'examples',
        },
    ],
},

Expected behavior

Should work and generate version aware link to the /examples URL (e.g. /next/examples when next is selected).

Actual behavior

It complains about such id not existing:

DocNavbarItem: couldn't find any doc with id "examples" in version 3.0". Available doc ids are: - examples/accept-user-input - examples/add-data-to-dataset - examples/basic-crawler - examples/capture-screenshot - examples/cheerio-crawler - examples/crawl-all-links - examples/crawl-multiple-urls - examples/crawl-relative-links - examples/crawl-single-url - examples/crawl-sitemap - examples/crawl-some-links - examples/forms - examples/http-crawler - examples/jsdom-crawler - examples/map-and-reduce - examples/playwright-crawler - examples/puppeteer-crawler - examples/puppeteer-recursive-crawl - examples/puppeteer-with-proxy - examples/skip-navigation - guides/apify-platform - guides/avoid-blocking - guides/cheerio-crawler-guide - guides/configuration - guides/docker-images - guides/got-scraping - guides/javascript-rendering - guides/jsdom-crawler-guide - guides/motivation - guides/proxy-management - guides/request-storage - guides/result-storage - guides/scaling-crawlers - guides/session-management - guides/typescript-project - introduction/adding-urls - introduction/crawling - introduction/first-crawler - introduction/introduction - introduction/real-world-project - introduction/refactoring - introduction/saving-data - introduction/scraping - introduction/setting-up - quick-start/quick-start - upgrading/upgrading-to-v1 - upgrading/upgrading-to-v2 - upgrading/upgrading-to-v3 - /guides - /examples - /upgrading

I also tried to put there doc: 'examples/index' without luck. Only thing that works is passing down one of the available doc ids as the error lists them (in other words, linking to some particular example, not to the generated index page).

Also note that the selection of active link seems to be broken if I change it to one of the actual example pages, e.g. doc: 'examples/accept-user-input'. With that the link is always active as long as I am on some doc item page (note the URL, the examples one is just /docs/examples so they dont collide anyhow):

Maybe a bit unrelated followup is the API link next to it - that is a link to https://github.com/milesj/docusaurus-plugin-typedoc-api plugin, it also supports versioning. How would I go about supporting version aware links for that one?

Your environment

• Public source code: https://github.com/apify/crawlee
• Public site URL: https://crawlee.dev
• Docusaurus version used: 2.0.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): not related
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): not related

Self-service

• I’d be willing to fix this bug myself.

[slorber]

@B4nan this seems related to a bug/annoying default behavior reported here: https://github.com/facebook/docusaurus/issues/5689#issuecomment-1017376748

Unfortunately, we don’t have any simple way to exclude the Example category subitem automatically or manually currently.

The only solution I can think of is to write some customized sidebarItemGenerator and run your own filtering there. https://docusaurus.io/docs/sidebar/autogenerated#customize-the-sidebar-items-generator

const filteredDocIds = ["examples"];

function isFiltered(item) {
  return item.type === "doc" && filteredDocIds.includes(item.id);
}

function filterSidebarItems(items) {
  return items
    .filter(item => !isFiltered(item))
    // recursive filtering (optional)
    .map(item => {
      if (item.type === "category") {
        return { ...item, items: filterSidebarItems(item.items) };
      }
      return item;
    });
}

module.exports = {
  plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return filterSidebarItems(sidebarItems);
        }
      }
    ]
  ]
};

Does it make sense?

[Josh-Cena]

Ah, so your sidebar contains things other than this generated index, and you want a versioned link that links to the generated index.

FWIW, we don’t have this—we also have a TODO in our own code because you can’t have a versioned link to a generated index in Markdown either. I’ll triage this as a feature request. Related to: https://github.com/facebook/docusaurus/issues/6041