[DO NOT MERGE] POC - unique versioning for some sections of the docs #906

pepopowitz · 2022-05-13T21:59:46Z

This PR will not be merged.

It's a proof of concept for how we could implement multi-versioning within the docs -- most of the docs use one versioning scheme, while some sections (Optimize, in this example) use a different one.

Demo of how this PR affects navigating the docs

…een docs instances

…tance

pepopowitz

Adding notes to help explain the changes.

pepopowitz · 2022-05-16T16:26:19Z

docs/components/concepts/what-is-camunda-platform-8.md

@@ -63,7 +63,7 @@ With [Tasklist](../tasklist/introduction.md), process owners can achieve end-to-

 ### Optimize

-[Optimize](../optimize/what-is-optimize.md) leverages process execution data to continuously [provide actionable insights](../../guides/improve-processes-with-optimize.md). Optimize specializes in BPMN-based analysis and can show users exactly what their process model needs for successful execution.


I actually didn't think to make this change -- VS code made it for me. But yes, we will be moving a whole bunch of content from one URL "folder" to another, so there will be a lot of content updates like this.

pepopowitz · 2022-05-16T16:28:17Z

docusaurus.config.js

@@ -31,6 +31,23 @@ module.exports = {
      },
    ],
    "./static/plugins/bpmn-js",
+
+    [
+      "@docusaurus/plugin-content-docs",


We're adding a second instance of the docs plugin. We can choose the base paths here, but for this POC it made sense to just use "optimize" since that was the only section I was moving.

If we have other components that use a third versioning scheme, which I think might be the case, we'd add a third docs instance here.

pepopowitz · 2022-05-16T16:33:26Z

docusaurus.config.js

+        lastVersion: "current",
+        versions: {
+          current: {
+            label: `latest`,
+          },
+        },


These are the settings that allow us to "pretend that the current version is a cut version", as indicated in the docs. This is nothing different from how we're doing it for the current docs.

But I'm adding a note here because I think I may have a follow-up POC that changes this to the 1st scenario described in those docs, and the approach that docusaurus takes, to treat the "current" version as "next/under-construction", and the "latest" version as the most highly-numbered release. Why? One issue I think we'll have with this work is the quantity of work involved to move all those docs over to the new section of the site. I think that if we were to switch over to this approach of having a "next/under-construction" version of the docs, we could work iteratively toward moving everything over to the right place, instead of having to do something like a long-living/very-large branch.

pepopowitz · 2022-05-16T16:34:31Z

optimize/what-is-optimize.md

@@ -4,6 +4,8 @@ title: What is Optimize?
 description: "Leverage process data and analyze areas for improvement."
 ---

+Yoooo this is version `latest`!!!


I had this marker here, and in the other versions, so that I could see clearly which docs I was viewing.

pepopowitz · 2022-05-16T19:47:03Z

optimize_sidebars.js

+    {
+      type: "link",
+      label: "Overview Components",
+      href: "/docs/components",
+    },


This will be time-consuming work, and probably difficult to maintain.

We'll have one sidebars file for each "docs instance" -- in this case, one for the main docs, and one for the optimize section. If we want to maintain the current structure of our docs navigation, we'll basically duplicate the main sidebars into this one -- except the links that cross over from one section to the other need to be rewritten using the non-shorthand format, like this. The shorthand format only works when the link target is within the same docs instance.

This is going to result in duplication of page titles, and also just be kind of annoying. I wonder if we could create a plugin that allows us to write in the shorthand format with some kind of token, and looks up/rewrites the information from the other docs instance.

pepopowitz · 2022-05-16T19:48:46Z

optimize_versioned_docs/version-3.8.1/userguide/collections-dashboards-reports.md

@@ -0,0 +1,41 @@
+---


Note the path in this file -- optimize_versioned_docs/version-3.8.1. This is, I think, what we're looking for -- we can use different versions for these docs than the rest of the components.

Many files after this one are the same deal -- moving into the new sections of the site.

pepopowitz · 2022-05-16T19:51:29Z

optimize_versions.json

@@ -0,0 +1 @@
+["3.9.0", "3.8.1"]


The versions for the optimize section are defined here, in a separate file, which is what allows us to use different versions for the two different sections.

Note that the name of this file is important, and is based on the name of the second docs plugin instance.

pepopowitz · 2022-05-16T19:52:33Z

sidebars.js

+// POC note: the majority of links in this file are within the same
+//   docs instance, so they can use the "shortcut" format.


This file is from the main docs site, so it's like the inverse of the other sidebars file in that most of the links here can be shortcut. Only the ones that bounce over to the optimize section need to be in the long format.

pepopowitz · 2022-05-16T20:01:17Z

src/theme/NavbarItem/DefaultNavbarItem.js

+import OriginalDefaultNavbarItem from "@theme-original/NavbarItem/DefaultNavbarItem";
+export default OriginalDefaultNavbarItem;


This was fun, I learned all about the concept of "swizzling", which is how we customize core docusaurus bits.

In this file, and several below it, we're literally wrapping the original docusaurus implementation. This seems silly, but we have to do it, because further down we want to override the implementation of another component in this same folder. If you replace one item inside of NavbarItem, you have to replace all of them. And since we don't actually want to change the implementation, we wrap them.

(I also learned that it's not just a made-up word)

pepopowitz · 2022-05-16T20:09:08Z

src/theme/NavbarItem/index.js

@@ -0,0 +1,29 @@
+import React from "react";


But here we do want to change the implementation, of the NavbarItem itself. The versions that appear in the navbar dropdown should vary depending on which section of the site you're visiting.

This component checks the current path, and if it pattern matches to the optimize section, sends the new docs plugin ID through to the version dropdown. Every other page falls back to the main docs versions.

pepopowitz · 2022-05-18T14:30:56Z

Closing this as it's for POC purposes.

pepopowitz added 5 commits May 13, 2022 15:05

move optimize docs into their own docs instance

ff73861

sidebars and optimize_sidebars point at each other when crossing betw…

34e5892

…een docs instances

add some comments

b983897

add some versions for optimize section

501e783

customize navbarItem to show different versions depending on docs ins…

f7f6632

…tance

pepopowitz marked this pull request as draft May 13, 2022 21:59

pepopowitz commented May 16, 2022

View reviewed changes

mary-grace assigned pepopowitz May 17, 2022

pepopowitz mentioned this pull request May 17, 2022

[DO NOT MERGE] POC - use docusaurus's recommended "next/latest" versioning practice #910

Closed

pepopowitz closed this May 18, 2022

pepopowitz mentioned this pull request May 24, 2022

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

Closed

pepopowitz mentioned this pull request Aug 2, 2022

Configure multi-instance versioning #1116

Closed

pepopowitz mentioned this pull request Aug 16, 2022

feat: set up optimize docs instance and move one doc over #1166

Merged

6 tasks

pepopowitz added the epic:optimize-versions label Nov 30, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DO NOT MERGE] POC - unique versioning for some sections of the docs #906

[DO NOT MERGE] POC - unique versioning for some sections of the docs #906

pepopowitz commented May 13, 2022 •

edited

Loading

pepopowitz left a comment

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz May 16, 2022

pepopowitz commented May 18, 2022

		@@ -63,7 +63,7 @@ With [Tasklist](../tasklist/introduction.md), process owners can achieve end-to-

		### Optimize

		[Optimize](../optimize/what-is-optimize.md) leverages process execution data to continuously [provide actionable insights](../../guides/improve-processes-with-optimize.md). Optimize specializes in BPMN-based analysis and can show users exactly what their process model needs for successful execution.

		// POC note: the majority of links in this file are within the same
		// docs instance, so they can use the "shortcut" format.

		import OriginalDefaultNavbarItem from "@theme-original/NavbarItem/DefaultNavbarItem";
		export default OriginalDefaultNavbarItem;

[DO NOT MERGE] POC - unique versioning for some sections of the docs #906

[DO NOT MERGE] POC - unique versioning for some sections of the docs #906

Conversation

pepopowitz commented May 13, 2022 • edited Loading

pepopowitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz commented May 18, 2022

pepopowitz commented May 13, 2022 •

edited

Loading