Versioned navbar item link to generated index

[B4nan]

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.

[Josh-Cena]

A type: "doc" item links by ID, which can be totally unrelated to the URL (via the slug front matter), so if it fails to find an ID, it will be unable to link to anything at all. If you want to link to a generated index page, maybe try type: "docSidebar"?

[B4nan]

maybe try type: "docSidebar"?

But how should I use that? It requires sidebarId, I have only one sidebar which is docs, using that makes it link to the first page in this sidebar.

Examples page is using the same sidebar as everything else. Its just a generated index page for the folder contents.

https://crawlee.dev/docs/examples
https://github.com/apify/crawlee/blob/master/website/sidebars.js#L49-L64

[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: #6041

[Josh-Cena]

@slorber I never understood why the type: "docVersion" item exists. Can its to be made reactive?

[B4nan]

I was trying to find a workaround via client side JS code that patches the href attributes of those 3 links, but to have them work I need to remove the ajax click handler and make real redirect. Is there a way to do an "ajax redirect" (so just like if I would click the link, but with a different href)? Something like what the <Link> component does as opposed to regular <a href>, but for programatic usage.

[Josh-Cena]

For the time being you can probably provide a custom NavbarItem. We don't have docs for it and it's quite late here, but let's see if @slorber has time to provide an example and/or some more insights

[slorber]

We'll support custom Navbar Items in the future and also structured the code so that you can already do this yourself today with swizzle (see #7231)

Agree we don't have a good way to link to generated index for now, either through navbar (this issue) or markdown links (#6041)

The best workaround I can suggest today would be to link to a examples/index.md doc in which you just render the generated-index cards manually with MDX:

# Examples

Here are all the examples:

import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>

Now you have a real doc to link to:
https://docusaurus.io/docs/sidebar/items#category-doc-link

[slorber]

@slorber I never understood why the type: "docVersion" item exists. Can its to be made reactive?

Probably not very useful, but it's just a simpler form of the version dropdown behavior: it shows the current version, you can click on it, and it links to the first doc in the first sidebar of that given version.

Now I'm not against enhancing it a bit, so that passing an explicit to would get automatically prefixed with /docs/version/ for example.

Similarly we could have a versioned markdown link like [my-generated-index-page](version:///category/my-generated-index-slug) 🤷‍♂️

[slorber]

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

That's a different topic that we'd rather discuss as a separate issue. It's a third-party plugin and I can't tell how you should use it. What I would do is probably create one plugin instance per version.

[B4nan]

Thanks for the details! I managed to make it work, although it felt like I met few bugs on the go I had to work around.

For example now I have the index page in examples folder, but it is still rendered in sidebar as well as in on the page. I though index.mdx will get ignored automatically (tried to use .md as well, no difference).

This is how the sidebar is defined:

{
    type: 'category',
    label: 'Examples',
    link: {
        type: 'doc',
        id: 'examples/examples',
    },
    items: [
        {
            type: 'autogenerated',
            dirName: 'examples',
        },
    ],
}

---
id: examples
title: Examples
---

import DocCardList from '@theme/DocCardList';
import { useCurrentSidebarCategory } from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items} />

https://crawlee.dev/docs/next/examples

[slorber]

@B4nan this seems related to a bug/annoying default behavior reported here: #5689 (comment)

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?