feat(v2): doc navbar item type

[slorber]

Motivation

Ability to link to a doc from the navbar, and have the link have a doc-sidebar-active class whenever that doc's sidebar is active.

This makes it possible to have tab-like navigation, see ReactNative website:

Note, in v1 this feature existed already with a quite similar API:

fixed #3320

Note: should we use this on Docusaurus website?
I've done so but maybe I should revert.
We should think better about how to organize v2 docs.

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

Tests, preview and dogfooding

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 8171d05

https://deploy-preview-3539--docusaurus-2.netlify.app

[slorber]

TODO:

• need to fix mobile
• need to fix older versions

[lex111]

This code will shift to Infima repo, right?

[slorber]

I don't think it necessarily has to, but not sure yet.

It's a CSS/infima breaking change, and those changes are only mandatory for sites that are willing to provide a tab bottom border for selected items (like RN website),

But sites could as well decide that just highlighting the link related to a sidebar (without the bottom layout) is enough. In such case, the change to Infima could be minimal and look like;

    &:hover,
    &--active,
+   &--group-active {
      color: var(--ifm-navbar-link-hover-color);
      text-decoration: none;
    }

https://github.com/facebookincubator/infima/blob/master/packages/core/styles/components/navbar.css#L132

I could even just apply the existing --active modifier and not modify Infima as all, wonder what's best.

[slorber]

My PR mostly focus on the behavior side of the navbar item (ie applying a className when any of the docs of the same sidebar is focused).

The styling side could be handled in a separate PR imho, just added this custom site CSS to demonstrate that the behavior is good enough to add this styling from the outside.

The point of this PR is not really to discuss how navbar links should look like between these 2 options:

Do you think I should revert the v2 custom styles (ie move back to simply coloring the navbar link? 2nd option) until we figure out how to make this through Infima

[lex111]

I could even just apply the existing --active modifier and not modify Infima as all, wonder what's best.

Oh, it's really easier, so maybe we choose this option?

[lex111]

We can merge this PR with current style changes, but I can do styling in Infima repo and after that provide new PR. вт, 6 окт. 2020 г., 14:37 Sébastien Lorber <[email protected]>:

…

***@***.**** commented on this pull request. ------------------------------ In website/src/css/custom.css <#3539 (comment)>: > @@ -96,3 +98,32 @@ html[data-theme='dark'] .DocSearch { var(--ifm-color-emphasis-100) 100% ); } + +.navbar__items > .navbar__item { My PR mostly focus on the behavior side of the navbar item (ie applying a className when any of the docs of the same sidebar is focused). The styling side could be handled in a separate PR imho, just added this custom site CSS to demonstrate that the behavior is good enough to add this styling from the outside. The point of this PR is not really to discuss how navbar links should look like between these 2 options: [image: image] <https://user-images.githubusercontent.com/749374/95196834-edddd280-07d8-11eb-9a7e-55f49fb002b0.png> [image: image] <https://user-images.githubusercontent.com/749374/95196857-fb935800-07d8-11eb-9bd0-2c4400a12ff4.png> Do you think I should revert the v2 custom styles (ie move back to simply coloring the navbar link? 2nd option) until we figure out how to make this through Infima — You are receiving this because your review was requested. Reply to this email directly, view it on GitHub <#3539 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABBUIO3JU5MSPXXKZXX3LFDSJL6RFANCNFSM4SE4Z2UA> .

[slorber]

Yes that's a possibility.

Do you think we should enable the tab-like CSS for all docusaurus sites?

Should I just apply the --active modifier in case we are browsing a doc of the same sidebar?

v1 had 2 distinct classes, to distinguish between active doc vs inactive doc but a doc of same "group" (ie sidebar) is active:

What about a --group-active modifier?

[slorber]

Going to revert my local CSS changes so that we can add this styling in a new PR if we want to. This way this PR would be minimal and only focus on the behavior and we can merge it asap.

Now I just highlight the element, no need for any CSS change:

As a backup here are the styles I used to get the tabs working, inspired by CSS on RN website:

:root {
  --ifm-navbar-padding-vertical: 0;
}

.navbar__items > .navbar__item {
  position: relative;
  height: 100%;
  display: flex;
  align-items: center;
}

.navbar__items > .navbar__item.navbar__link.navbar__link--active::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  width: 100%;
  height: 0.25rem;
  background-color: var(--ifm-link-color);
}
.navbar__items > .navbar__item.navbar__link.doc-sidebar-active::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  width: 100%;
  height: 0.25rem;
  background-color: var(--ifm-link-color);
}
.navbar__items > .navbar__item.navbar__link.doc-sidebar-active {
  color: var(--ifm-link-color);
}

[lex111]

Do you think we should enable the tab-like CSS for all docusaurus sites?

Yes I think it's great!

Should I just apply the --active modifier in case we are browsing a doc of the same sidebar?
What about a --group-active modifier?

Is it really necessary? I don't really understand, but can we use only class with --active modifier?

[slorber]

Is it really necessary? I don't really understand, but can we use only class with --active modifier?

Not sure, hard to predict, but as it's a new feature as long as people don't ask for it... Made the "group active" class configurable, with navbar__link--active as default, so we should be fine.

Leaving right now but if CI pass and it's ok for you, you can merge ;)

[lex111]

The only thing that confuses me is that we have now two essentially duplicate links, and therefore two navbar items are highlighted, although there should be one.

I think we need to move versions dropdown from navbar to doc sidebar. Something like on the Vue docs:

https://vuejs.org/v2/guide/

Or we can follow the Kubernetes Docs path - not show the currently browsing version in the navbar, but just a label "Versions":

https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/

[slorber]

Yes that could be a nice idea to have the version dropdown in the sidebar, we should probably do a redesign pass of the Docusaurus UX at some point, including the mobile experience.

The duplicate highlighting is annoying that's true. However I don't think we can solve this in a generic way, as the user can compose the navbar items how he wants to, he can add 2 items from the same sidebar and end up by default with 2 highlighted items anyway (which is quite similar to what happens in this case btw).

I've added an option to make it more flexible, and so that our site is less confusing too:

        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownActiveClassDisabled: true,
        },

Do you think it's good enough to get merged?

To me it's fine, as we don't force any user to use this new doc item type anyway

[lex111]

LGTM

[slorber]

Thanks

About the K8 versions drropdown, it's indeed possible to make the label static and provided by option. Not sure if it's better but it's a possibility. However in the past many users asked for the current version to be visible in the navbar so not sure people would be interested by that VS the current dropdown.