[DO NOT MERGE] POC: Share sidebar definitions between doc plugin instances

[pepopowitz]

This PR will not be merged.

This is a proof of concept for one way we could share sidebar definitions between the main /docs section of the site and the alternate /optimize section.

This research was spawned by this comment on the POC for handling multiple versions. With the changes in that PR, we'd end up with two kinds of duplication in our sidebars definitions:

1. The structure duplicated between the main sidebars definition and the optimize sidebars definition
2. The title duplicated between every document and exactly one sidebars definition file.

This PR solves #1 above, but does not solve #2. It's not an ideal solution, but it accomplishes at least a portion of the original goal.

I'm uncertain about how helpful these changes are, so I'm open to feedback in that regard. Is this an improvement over what we had in #906 ?

Summary of changes

• sidebars.js is updated to include only long-format links, instead of short-format doc IDs. This includes duplicating sidebar titles from the docs themselves.
• optimize_sidebars.js is updated to import the actual sidebar content from sidebars.js, eliminating duplication of the sidebar navigation structure.
• displayed_sidebar prop needs to be added to frontmatter of all docs, so that docusaurus knows which sidebar to show.
• Remove any sidebar_label props in docs, because they no longer have an effect. (Not seen in this PR, but also a pretty insignificant amount of work.)

More details inline with the code, in the "Files changed" tab.

Visual proof that navigation still functions as expected

sidebar-dupes.mov

Limiting constraints

• The global data generated by docusaurus that captures all content on the site is intentionally limited for performance, and does not include things like page titles.
• Labels for the sidebars, and routes for doc pages, are generated by the docs plugin. (Because they can be overridden in doc frontmatter).
• Thus any solution we come up with will need to either get doc info from the two docs plugins, or borrow logic from the docs plugins to translate the doc source files into routes & titles.

Other approaches considered

A plugin that reads a single sidebars definition, and translates a shortcode like @docs/... to a sidebar item from the main docs instance, and @optimize/... to a sidebar item from the alternate optimize instance.

Blockers:

1. Plugins load asynchronously, so we can't make this plugin load after the two docs plugins.
2. Plugins load in isolation of each other, so we wouldn't have access to the output of the two docs plugins.

A script that runs pre-build to translate a single sidebar definition file into long-format links, including titles.

Blocker: Running the script prior to build means we don't get any docusaurus functionality. We'd need to borrow a bunch of logic from docusaurus to construct a usable model for our script.

Swizzle the DocSidebar theme component, and have it pull sidebar items from the appropriate docs instance.

Blocker: The sidebars data that comes out of the docs plugin is in a fully presentable state, including titles and routes. It's too late at this point in the lifecycle -- all sidebar items have been expanded. If we wanted to override any existing plugins or themes, we'd have to do it in the docs plugin itself.

Customize the docs plugin and find a way to give one instance access to docs in the other instance

Blockers:

1. Other than themes, plugins can't be swizzled to customize them. To customize the docs plugin, we'd have to create our own plugin and borrow all the logic from the original.
2. I sincerely doubt we'd be able to figure this out, since docusaurus itself doesn't already provide a way for instances to access each others' content.

[pepopowitz]

I'm not exactly sure why these need to be added.

The effect of not adding it is that no sidebar shows up for this doc.

From the docs, it sounds like this property is needed to narrow down which "sidebar" to use when there's ambiguity. I initially thought "oh that's because I have two sidebars files with all the same sidebars in them", but even then, specifying "Components" doesn't tell it which Components do use, since it's defined in both sidebars files.

In the end I just said 🤷 and slapped these in, figuring it wouldn't be a terrible amount of work to add these to every doc -- potentially automatable, even.

[pepopowitz]

This is the main goal of this PR -- remove the duplication of the entire structure across the two sidebars files.

[pepopowitz]

This is the big downside to this solution. We can no longer use shorthand doc-id items, because this file is loaded by both doc plugin instances -- for one of them, the doc-id would be usable, but for the other it's an unknown doc. So, all items in the sidebars become the long-format link definition.

• Unfortunately, we'll have to duplicate the label into all of these items from their associated doc.
• Note that the href is different in these two examples than their shorthand versions on the left side. This is because the doc-id on the left isn't always the same as the slug for the doc. In most cases, we won't have to change this; in a few, we will.
• A side-quest of this work would be to remove any sidebar_label props in the associated docs -- I didn't do that in this PR, and it wouldn't hurt to leave them...but that property is meaningless now, since we're specifying the sidebar label for every item in this file.

[christinaausley]

This isn't a terribly deal-breaking downside for me. If we need to adjust this meta data, it may take some time to clean up, but IMO is worth it for the long-term goal of achieving unified multi-instance.

[pepopowitz]

Closing this as it's for demonstration purposes only.