[v2] Sidebar menu also set active the Navbar menu

[prma85]

🚀 Feature

When creating a multi-level docs page with different menus, normally we go with

sidebar.js

{
  components_menu: [
        "components/status",
        "components/button",
        "components/card",
        "components/checkbox",
        "components/datepicker"
  ],
  web_dev_api_menu: [
        "web-dev-docs/api/status",
        "web-dev-docs/api/components/alert",
        "web-dev-docs/api/components/analytics",
        "web-dev-docs/api/components/antd",
        "web-dev-docs/api/components/auth"
  ],
}

And for my nav bar, I would go with
docusaurus.config.js

navbar: {
  links: [
    {
      to: "docs/components/status",
      label: "Components",
      position: "left",
    },
    {
      to: "docs/"web-dev-docs/api/status",
      label: "Web-api",
      position: "left",
    },

However, there is no link between the navbar and when opening a Navbar, I will get only the menus for that navbar item, and due to this, the navbar link doesn't keep active when switching the sidebar items.

Motivation

Be able to create multi-level/layers docs site and keep the navbar menu active

Pitch

Normally when creating a docs page, and it is too big or too complex (for example, a design system docs or API docs), we need to divide it by sections. As today, if we divide the docs, we don't have a clear indication of what is the active section.

Maybe, the Navbar API could be extended to add an optional property to link the sidebar object to be active
For example:

navbar: {
  links: [
    {
      to: "docs/components/status",
      label: "Components",
      position: "left",
      sidebar: "components_menu"
    },

So, when navigating on any items of the components_menu array, it will keep the navbar item Components active

[slorber]

Hi,

If all the docs of your sidebar 1 have /docs/components/ url prefix, and all the docs of your sidebar 2 have docs/web-dev-docs/api/ prefix, you can highlight the navbar links by using the activeBasePath / activeBaseRegex features, that will "activate" the items when you navigate to them.

https://v2.docusaurus.io/docs/theme-classic/#navbar

Nevertheless, I think we should support this by default without requiring you to activate with explicit path/regex option on purpose. Will try to understand what happened, because whil reading the code I feel like this auto activation of navbar link was explicitly disable for some reason.

[prma85]

Hey @slorber
Thanks for your reply.
It works like a charm for the simple navbar item. However, if the item as sub-items (rendered as dropdown, the active class is not applied to it).

Not sure if it is the desired behaviour. Maybe it is a small bug?

[slorber]

you have to assign a path/regexp to each dropdown element.

See how it works on the docusaurus 2 website:

if we can do it, you can probably do the same :)

[prma85]

Yep, totally agree.

This is my navbar:

links: [
  {
    to: "docs/foundations-and-experiences/ux-principles",
    label: "Foundations",
    position: "left",
    activeBasePath: "docs/foundations-and-experiences",
  },
  {
    to: "docs/language-and-design/colors",
    label: "Design",
    position: "left",
    activeBaseRegex: "docs/(language-and-design|designer)",
  },
  {
    to: "docs/components/status",
    label: "Components",
    position: "left",
    activeBasePath: "docs/components",
  },
  {
    label: "Web Dev",
    position: "right",
    activeBaseRegex: "docs/web-dev/(guides|api|support|fed-team)",
    items: [
      {
        label: "Docs",
        to: "docs/web-dev/guides/creating-a-new-app",
        activeBasePath: "docs/web-dev/guides",
      },
      {
        label: "Support",
        to: "docs/web-dev/support/help",
        activeBaseRegex: "docs/web-dev/(support|fed-team)",
      },
      {
        label: "Storybook",
        to: "/storybook",
        activeBasePath: "storybook",
      },
      {
        label: "API",
        to: "docs/web-dev/api/contributing-new-features",
        activeBasePath: "docs/web-dev/api",
      },
    ],
  },
  {
    to: "docs/mobile-dev/mobile-dev-intro",
    label: "Mobile Dev",
    position: "right",
    activeBasePath: "docs/mobile-dev",
  },
],

All the active links work for the exception of the Web-dev that is a Dropdown menu 🤔
Looking into the docusaurus navbar (https://github.com/facebook/docusaurus/blob/master/website/docusaurus.config.js) doesn't look too much difference in how I am creating it.

But it still doesn't active the navbar item, only the sub-items

The li has the active class, but not the dropdown

[slorber]

I'm sorry but I'm unable to understand what you want. Can you display screenshots, link to code or something?

Here you can see 2 items can get highlighted: Docs and 2.0-alpha.54. You'd want something else to be highlighted?

For me, when you say "the dropdown menu", this is the whole ul with all the versions, it is not supposed to "activate", what do you expect from activating this menu

Can you draw something in https://excalidraw.com/ so that I understand exactly what UI you want?

[prma85]

Sorry for not being clear
When I am saying dropdown menu, I mean the main item/title and not the internal list

The code I sent before is for this menu.
I can see the menu items inside of the dropdown being active but not the dropdown itself
Also, looking in the HTML generated, the div with the dropdown title as no active class

In my case, the menu is Web Dev -> Docs. Docs is highlighted, but not Web Dev

  {
    label: "Web Dev",
    position: "right",
    activeBaseRegex: "docs/web-dev/(guides|api|support|fed-team)",
    items: [
      {
        label: "Docs",
        to: "docs/web-dev/guides/creating-a-new-app",
        activeBasePath: "docs/web-dev/guides",
      },
  }

[slorber]

Will have to check tomorrow but maybe it requires a to attribute on the parent item Le mar. 21 juil. 2020 à 18:02, Paulo Andrade <[email protected]> a écrit :

…

Sorry for not being clear When I am saying dropdown menu, I mean the main item/title and not the internal list [image: image] <https://user-images.githubusercontent.com/1236101/88077700-c6ac2900-cb38-11ea-886e-f2119f3e1852.png> The code I sent before is for this menu. I can see the menu items inside of the dropdown being active but not the dropdown itself Also, looking in the HTML generated, the div with the dropdown title as no active class In my case, the menu is Web Dev -> Docs. Docs is highlighted, but not Web Dev { label: "Web Dev", position: "right", activeBaseRegex: "docs/web-dev/(guides|api|support|fed-team)", items: [ { label: "Docs", to: "docs/web-dev/guides/creating-a-new-app", activeBasePath: "docs/web-dev/guides", }, } — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3067 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PRR37EPFG437I7PCPLR4W3ZDANCNFSM4O23RWLQ> .

[slorber]

@prma85 according to what I see in the code, activeBasePath is only used if you have a "to" in your parent element. Without it, it won't be a ReactRouter link, which provides us the active feature.

Can't you add a "to" attribute?

[prma85]

@slorber yes, it did the trick
But since this menu has no real link, I add the following
to: "#",
and it worked
thanks \o/

[slorber]

great

yes this is probably not very convenient but at least there's a workaround. Does "#" has any unintended side-effect?

[prma85]

I didn't notice any side-effect. Looks all good :)

[slorber]

Great. Tell me if alpha 59 gives you any trouble

[prma85]

trouble

Hey @slorber, I just updated it to alpha 59 and not it generates errors on build 🤔 (works with yarn start tho)

TypeError: sidebar.map is not a function

(undefined) TypeError: sidebar.map is not a function
    at DocSidebar (main:125515:4742)
    at d (main:128597:498)
    at $a (main:128600:16)
    at a.b.render (main:128605:476)
    at a.b.read (main:128605:18)
    at Object.renderToString (main:128615:364)
    at serverEntry_render (main:202384:375)

And this is my sidebar.js (works fine on alpha 58)

[slorber]

Hi,

This is surprising, unfortunately I'm not able to reproduce.

I need more infos, if you can give me access to your site's code (or create a small repro) that helps.

Also I need to see the full content of the sidebar file (+ all the versioned sidebar files if available).

You can try to debug this with dichotomy: remove versions, remove docs, remove sidebar content, until your site work

[prma85]

🤔
the yarn start still works, but yarn build fails on building server with this error

I got my sidebars.js as simpler as possible

module.exports = {
  docs: [
    {
      type: "category",
      label: "Design",
      items: [
        "language-and-design/colors",
        "language-and-design/typography",
        "language-and-design/spacing",
        "language-and-design/empty-states",
        "language-and-design/data-entry",
        "language-and-design/visibility-security-and-permissions",
      ],
    }
  ]
};

But I am still getting the error TypeError: sidebar.map is not a function 🤔

Repo: https://github.com/prma85/iQ.design.system.docs

[prma85]

I only change was updating from alpha 58 to alpha 59
using alpha 58 still works, but since my azure pipeline has a yarn upgrade to always use the lastest internal versions of some packages, it also updates the docusaurus 🤔
so, it fails on the build and deploys 😢

[slorber]

@prma85 in such case you shuld avoid using semver ranges in your package.json so that azure stick to existing versions? This is very strange to have your CI not respecting lockfile, why is that?

About your problem, I don't have access to this repo that is private, if you send me an invite I'll look at this

[prma85]

It is on propose not using the lock file. I have some custom packages from a mono repo used there (like storybook) and the idea is on each deploys it will always get the latest version of the packages. Publishing a new version of the package will trigger a deploy for the docs website

I send the invite

But I got the issue solved. 🎉
I create a new docusaurus project from scratch to compare.
My sidebar now is working, and the issue wasn't anything with the sidebar (even the build telling a problem in the sidebar).

In my website, I am using a custom DocPage to add styling to the edit button and add an extra button for feedback (which will create an issue in the repository)

And looks like you guys changed the implementation for it, so, my swizzle wasn't valid anymore.

I got the same issue before when updating to alpha 58, but at that time, the build was complaining about the docpage, but now, it was complaining about the sidebar.

Doing a new swizzle for the DocPage and adding my custom code (an useEffect to execute an external function) solved the issue.

Now the issue is with links. It is complaining about broken links.

For example,

- Page path = /docs/web-dev/faq/hub-v1-faq:
   -> link to /../guides/configuring-environments#azure-devops-authentication (resolved as: /guides/configuring-environments)

The link is correct since I have the /docs/web-dev/guides/ folder. Navigating on the website it also works, but the build is complaining that the link is not valid. The resolved is getting links in relation to the main website instead of the folder that I am right now.

However, another link in the same file is resolved without issue (../guides/v1/configuring-old-v1-environments.md).

Any ideas?

[slorber]

Thanks, I see

Sorry to have to change some implementation details of that component, unfortunately, it's required to fix some issues in the docs plugin. It is likely to happen again on next versions because there are other things I'd like to fix regarding the docs plugin and the exposed theme api surface which is currently a bit blurry and likely to cause such breaking changes.

About the links, this is probably already fixed (leading / appended by mistake) and going to be released soon, but please give me the markdown of that link to double-check

[prma85]

@slorber Thanks

On v1 I was just adding a custom script and then, when loading the page, it was looking for the edit link and doing the necessary work for adding the extra button.

This doesn't work on v2 because the page is loaded and not the content for the first time. There are some milliseconds there with waiting for a render. The alternative was using useEffect in the DocPage. I could do a setTimeout, but it wouldn't work anymore when the link is changed since I can't see any event is triggered when the route changes on the window. If there is another option I would to love to use it, like, the possibility to add a class to the edit page or extra buttons through docusaurus.config.js ;)

I checked the links and looks all good.
Any intention to add more power to the onBrokenLinks?
I was looking for an option to be able to ignore some links. For example, I would like to ignore the dev.azure.com since these links are normally private and docusaurus will not be able to check if it is valid or not.

Example:
Broken links found!

- Page path = /docs/web-dev/concepts/architecture:
   -> link to /(https://dev.azure.com/iqmetrix/Hub/_packaging?_a=feed&feed=iqmetrix) (resolved as: /(https://dev.azure.com/iqmetrix/Hub/_packaging)

and the MD file has the following content:

## NPM Registry

| int / rc / prod |
| ---------------------- |
| [iQmetrix registry]    |

[iqmetrix registry]: (https://dev.azure.com/iqmetrix/Hub/_packaging?_a=feed&feed=iqmetrix)

[slorber]

On v1 I was just adding a custom script and then, when loading the page, it was looking for the edit link and doing the necessary work for adding the extra button.

This doesn't work on v2 because the page is loaded and not the content for the first time. There are some milliseconds there with waiting for a render. The alternative was using useEffect in the DocPage. I could do a setTimeout, but it wouldn't work anymore when the link is changed since I can't see any event is triggered when the route changes on the window. If there is another option I would to love to use it, like, the possibility to add a class to the edit page or extra buttons through docusaurus.config.js ;)

Sorry but I don't understand what you try to do. If this is not related to this issue at all, I'd rather discuss about this in another issue where you give me all the details, screenshots of v1 vs v2 etc...

Any intention to add more power to the onBrokenLinks?
I was looking for an option to be able to ignore some links. For example, I would like to ignore the dev.azure.com since these links are normally private and docusaurus will not be able to check if it is valid or not.

All links with a protocol are not checked (it is a bug that adds a weird / at the beginning and let us think it's an absolute internal link, but it will be fixed very soon)