Multiple components - single docs repo

[compojoom]

Hi,
We are looking into docusaurus for our docs website. Our project is composed of several components and we would ideally prefer to have them all in a single documentation website. The navigation structure would be something like:
component1

• getting started
  component2
• getting started

The problem we have is versioning. Our components are being updated independently of each other and we cannot have a single global version. Is it somehow possible to have multiple versions per component?
Per default the docs would show the latest version for every component. And then the user would be able to just say - show me an old version of componentX?

Anyone been dealing with a similar problem?

[slorber]

It is possible if you use one instance of the docs plugin per componentxzo that each comp has a different version. However I'm not sure the ux would be so great by default. We mostly do this so that you can have an ios + android sdk with different versions. Having thousands of docs plugin instance could be annoying to maintain. Le mar. 25 août 2020 à 14:39, Daniel Dimitrov <notifications@github.com> a écrit :

…

Hi, We are looking into docusaurus for our docs website. Our project is composed of several components and we would ideally prefer to have them all in a single documentation website. The navigation structure would be something like: component1 - getting started component2 - getting started The problem we have is versioning. Our components are being updated independently of each other and we cannot have a single global version. Is it somehow possible to have multiple versions per component? Per default the docs would show the latest version for every component. And then the user would be able to just say - show me an old version of componentX? Anyone been dealing with a similar problem? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3332>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PQKZI6SKHIVAEJPDHDSCOWHFANCNFSM4QKTI57A> .

[compojoom]

Thanks for the reply!
Well, yes. I think that we'll leave it to only 1 version for most components. And have a couple that have different version (APIs).

I'll give it a go! thanks!

ah, @slorber you do this in docusaurus v2 or v1?

[slorber]

Docs plugin is v2 only. Le mer. 26 août 2020 à 06:46, Daniel Dimitrov <notifications@github.com> a écrit :

…

Thanks for the reply! Well, yes. I think that we'll leave it to only 1 version for most components. And have a couple that have different version (APIs). I'll give it a go! thanks! ah, @slorber <https://github.com/slorber> you do this in v2 or v1? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3332 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PWXC7BHBADYEOYQ7TTSCSHTHANCNFSM4QKTI57A> .

[compojoom]

Ok, I got some time to experiment and I think that I managed to achieve what I wanted.

@slorber as you said the trickiest part was the UI. I still need to experiment a little, but currently I have it setup as follows.

doc plugin configured for componentX (it reads from componentX folder)

and the classic preset configured to read everything from docs - so basically all components that don't need versioning are in docs.

I wanted to show the dropdown with the versions onle when on the componentX page and not on the other docs.

I ended up swizzling the DocsVersionDropdownNavbarItem from classic-theme.

import React from 'react';
import OriginalDocsVersionDropdownNavbarItem from '@theme-original/NavbarItem/DocsVersionDropdownNavbarItem';
import {useLocation} from '@docusaurus/router';

const DocsVersionDropDown = (props) => {
  const {pathname} = useLocation();
  const {displayOnlyWhenPathIncludes, ...rest} = props

  if(displayOnlyWhenPathIncludes && !pathname.includes(displayOnlyWhenPathIncludes)) {
    return null
  }

  return <OriginalDocsVersionDropdownNavbarItem {...rest} />
}


export default DocsVersionDropDown

Basically with this I render the original version dropdown when the pathname includes a string I specify in the docusaurus config.
With this I could configure it so that I display different version dropdowns depending on the current doc plugin instance.
My navbar config looks like this:

        {
          type: 'docsVersionDropdown',
          position: 'right',
          docsPluginId: "componentX",
          // Add additional dropdown items at the beginning/end of the dropdown.
          dropdownItemsBefore: [],
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],

          // Do not add the link active class when browsing docs.
          dropdownActiveClassDisabled: true,
          displayOnlyWhenPathIncludes: 'blabla'
        },
        {
          type: 'docsVersionDropdown',
          position: 'right',
          // Add additional dropdown items at the beginning/end of the dropdown.
          dropdownItemsBefore: [],
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],

          // Do not add the link active class when browsing docs.
          dropdownActiveClassDisabled: true,
          displayOnlyWhenPathIncludes: 'docs'
        },

@slorber Do you think that this could generally be useful? I could create a PR with those modifications.

[slorber]

@compojoom that's an interesting usecase.

What I understand is that you want a different navbar depending on the current location.
Somehow, some navbar items "activates" according to some conditions.
It may be useful to others, but we need to figure a good and flexible API if we want to add such feature in core, and make it generic so that it can apply by default to all themes, all navbar items, and many situations.

[compojoom]

Yes, exactly. I changed my code to use customFields so that I can provide my config based on pluginID.

I actually needed a custom github button in the navbar. If on pageX -> show github link that points to repo X, if on pageY -> show github link that points to repo Y.
It would have been nice if the navbar links could support custom react components. I had to override the Navbar component to place my custom component that renders different things depending on the current page.

[slorber]

It would have been nice if the navbar links could support custom react components. I had to override the Navbar component to place my custom component that renders different things depending on the current page.

I'd like to make this possible, but not sure how yet. The navbar is quite static and not easy to customize without swizzling