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

docs/components/components-overview.md

@@ -13,7 +13,7 @@ This section contains product manual content for each component in Camunda Platf
 - [Modeler](modeler/about-modeler.md) - Documentation on Camunda's modeling tools, including Web Modeler and Desktop Modeler.
 - [Zeebe Engine](zeebe/zeebe-overview.md) - Complete documentation for Zeebe.
 - [Operate](operate/operate-introduction.md) - User guide for monitoring and troubleshooting your process with Operate.
-- [Optimize](optimize/what-is-optimize.md) - Detailed user guide for working with Optimize to improve your processes by identifying constraints in your system.
+- [Optimize]($optimize$/what-is-optimize) - Detailed user guide for working with Optimize to improve your processes by identifying constraints in your system.
 - [Tasklist](tasklist/introduction-to-tasklist.md) - Documentation for working with user tasks in Tasklist.
 - [Integration Framework](integration-framework/introduction.md) - Documentation on the Camunda framework to integrate with outside systems.
 

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

@@ -63,7 +63,7 @@ With [Tasklist](../tasklist/introduction-to-tasklist.md), process owners can ach
 
 ### 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.
+[Optimize]($optimize$/what-is-optimize) 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.
 
 ### Console
 

docs/components/modeler/web-modeler/start-instance.md

@@ -21,5 +21,5 @@ You can also specify variables written to the process context at startup. The va
 ```
 
 :::note
-You can also define the success of your processes by setting key performance indicators (KPIs) for your process using [Optimize](../../optimize/what-is-optimize.md).
+You can also define the success of your processes by setting key performance indicators (KPIs) for your process using [Optimize]($optimize$/what-is-optimize).
 :::

docs/components/operate/userguide/basic-operate-navigation.md

@@ -36,4 +36,4 @@ Here, see details about the process instance, including the instance history and
 
 ![operate-view-instance-detail](./img/operate-view-instance-detail.png)
 
-To visualize the performance of process instances, we recommend utilizing [Optimize](../../optimize/what-is-optimize.md).
+To visualize the performance of process instances, we recommend utilizing [Optimize]($optimize$/what-is-optimize).

docs/guides/improve-processes-with-optimize.md

@@ -15,7 +15,7 @@ Optimize offers business intelligence tooling for Camunda customers. By leveragi
 
 With Optimize, review heatmap displays for instances which took longer than average to discover long-running flow nodes. As a result, reap actionable insights and rapidly identify the constraints of your system.
 
-For an in-depth overview of Optimize’s capabilities, visit our [Optimize documentation](../components/optimize/what-is-optimize.md).
+For an in-depth overview of Optimize’s capabilities, visit our [Optimize documentation]($optimize$/what-is-optimize).
 
 ## Set up
 

docs/guides/introduction-to-camunda-platform-8.md

@@ -14,7 +14,7 @@ Camunda Platform 8 consists of six [components](/components/components-overview.
 - [Zeebe](/components/zeebe/zeebe-overview.md) - The cloud-native process engine of Camunda Platform 8.
 - [Tasklist](/components/tasklist/introduction-to-tasklist.md) - Complete tasks which require human input.
 - [Operate](/components/operate/operate-introduction.md) - Manage, monitor, and troubleshoot your processes.
-- [Optimize](/components/optimize/what-is-optimize.md) - Improve your processes by identifying constraints in your system.
+- [Optimize]($optimize$/what-is-optimize) - Improve your processes by identifying constraints in your system.
 
 For more conceptual information about Camunda Platform 8, see [What is Camunda Platform 8](components/concepts/what-is-camunda-platform-8.md).
 

docs/guides/setting-up-development-project.md

@@ -14,7 +14,7 @@ keywords: [get-started, local-install]
 - [Desktop Modeler](https://camunda.com/download/modeler/)
 - [Operate](/self-managed/operate-deployment/install-and-start.md)
 - [Tasklist](/self-managed/tasklist-deployment/install-and-start.md)
-- [Optimize](../components/optimize/what-is-optimize.md)
+- [Optimize]($optimize$/what-is-optimize)
 
 ## Setting up your project
 

docusaurus.config.js

@@ -1,3 +1,5 @@
+const versionedLinks = require("./src/mdx/versionedLinks");
+
 module.exports = {
   title: "Camunda Platform 8",
   tagline: "Documentation for all components of Camunda Platform 8",
@@ -32,6 +34,16 @@ module.exports = {
       },
     ],
     "./static/plugins/bpmn-js",
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "optimize",
+        path: "optimize",
+        routeBasePath: "optimize",
+        beforeDefaultRemarkPlugins: [versionedLinks],
+        sidebarPath: require.resolve("./optimize_sidebars.js"),
+      },
+    ],
   ],
   scripts: [],
   themeConfig: {
@@ -207,6 +219,7 @@ module.exports = {
           // Please change this to your repo.
           editUrl:
             "https://github.com/camunda/camunda-platform-docs/edit/main/",
+          beforeDefaultRemarkPlugins: [versionedLinks],
         },
         blog: false,
         theme: {

hacks/generateOptimizeSidebars.js

@@ -0,0 +1,70 @@
+// Set this prefix based on which version of docs you're viewing
+//   when generating the Optimize sidebars.
+//   It will be removed from all generated URLs, so that the version can be
+//   prepended in one place instead of every single link.
+const docsAndVersionUrlPrefix = "/docs/next/";
+
+// From an anchor in the sidebar, generates a call to a helper function
+//   based on the link text and path. See optimize_sidebars.js for what
+//   this helper function is and how it's used.
+function mapToDocsLink(a) {
+  return `docsComponentsLink("${a.innerText}", "${a.pathname.replace(
+    docsAndVersionUrlPrefix,
+    ""
+  )}"),`;
+}
+
+// From a category in the sidebar, generates sidebar definitions for it and its children.
+function buildCategory(li) {
+  const title = li.querySelector(
+    ":scope > div > .menu__link--sublist"
+  ).innerText;
+
+  const children = Array.from(li.querySelectorAll(":scope > .menu__list > li"));
+  const childrenMapped = children.map(buildLi);
+
+  return `
+    {
+      "${title}": [
+        ${childrenMapped.join("\n")}
+      ],
+    },
+  `;
+}
+
+// From an individual page in the sidebar, generates a sidebar definition.
+function buildLink(li) {
+  const anchor = li.querySelector(":scope > .menu__link");
+  return mapToDocsLink(anchor);
+}
+
+// From an item in the sidebar, generates the appropriate definitions.
+function buildLi(li) {
+  if (li.classList.contains("theme-doc-sidebar-item-link")) {
+    return buildLink(li);
+  }
+
+  if (li.classList.contains("theme-doc-sidebar-item-category")) {
+    return buildCategory(li);
+  }
+}
+
+// The root of the sidebar menu.
+const root = document.querySelector(".theme-doc-sidebar-menu");
+
+// Generates the sidebar definitions for the entire menu.
+function buildSidebars() {
+  const items = Array.from(root.querySelectorAll(":scope > li"));
+
+  const mappedItems = items.map(buildLi);
+
+  return `{
+    Components: [
+      ${mappedItems.join("\n")}
+    ]
+  }
+  `;
+}
+
+// Copies the generated sidebar definitions to the clipboard.
+copy(buildSidebars());

hacks/generateOptimizeSidebars.md

@@ -0,0 +1,68 @@
+# Generating Optimize sidebars
+
+## Why?
+
+With the Optimize docs living in their own docusaurus docs instance, we need to synchronize sidebar definitions across both instances. This provides a stable left nav for the user.
+
+Unfortunately docusaurus instances do not have access to each other's documents, so any links that cross instances need to be defined as URLs instead of document IDs.
+
+This script crawls the left nav of the site you're viewing, and generates a sidebar definition file full of URL-based links. It needs to be corrected for links that are _within_ the `optimize` docs instance, because it's not smart enough to generate doc-based links for them, but it prevents us from having to manually identify every page title/URL in the main `docs` instance.
+
+The script is run in the browser dev tools console, and the results are pasted into the `optimize_sidebars.js` file.
+
+## How?
+
+1. Visit docs.camunda.io
+2. Fully expand the entire left nav
+
+   Docusaurus doesn't emit all levels of the nav on initial render. Nested levels get emitted only when they're viewed (i.e. you expand their parent section).
+
+   The sidebar generation script operates on the DOM. Any levels of the nav that aren't in the DOM yet won't be included in the generated items.
+
+   I do this manually, because it doesn't take long, but you could script this step if you wanted to.
+
+   Tip: you can identify if there are any un-expanded menu categories by querying for them in your browser dev tools console:
+
+   ```javascript
+   > document.querySelectorAll(".menu__link--sublist-caret[aria-expanded=false]").length
+   ⋖ 0
+   ```
+
+   If that statement returns any number other than 0, there are unexpanded categories remaining.
+
+3. Paste the contents of generateOptimizeSidebars.js into your browser dev tools console
+
+   - Make sure the value of `docsAndVersionUrlPrefix` is correct based on the version of docs that you're viewing. This value will be stripped from all generated URLs, so that the `optimize_sidebars.js` file can prepend the correct version in only one place instead of every single link. (This will help us avoid a large find/replace when versioning optimize docs.)
+
+   - The last statement of the script copies the generated sidebars into your clipboard.
+
+4. Paste the results into the optimize_sidebars.js file
+
+   - The results do not include the statement `module.exports = `, so leave that part in 😅.
+
+   - Make sure the results get formatted, as the script generates an object that does not match prettier's desired format.
+
+5. Replace/revert any Optimize links that exist within the optimize docs
+
+   The script generates URL-based links for _all_ items in the sidebar; we want doc-based links for the Optimize docs.
+
+   #### Example
+
+   The script generated this link for me:
+
+   ```javascript
+       docsComponentsLink(
+         "What is Optimize?",
+         "components/optimize/what-is-optimize/"
+       ),
+   ```
+
+   But I revert this to the doc-based link (in shortcut format):
+
+   ```javascript
+       "what-is-optimize",
+   ```
+
+6. Smoke-test the navigation locally
+
+   Note that sidebars files may not be watched by docusaurus's local server. You might need to restart your local server to pick up changes.

docs/components/optimize/what-is-optimize.md → optimize/what-is-optimize.md

@@ -5,7 +5,7 @@ description: "Leverage process data and analyze areas for improvement."
 ---
 
 :::note
-New to Optimize? Visit our introductory guide to [Optimize](/guides/improve-processes-with-optimize.md) to get started.
+New to Optimize? Visit our introductory guide to [Optimize]($docs$/guides/improve-processes-with-optimize/) to get started.
 :::
 
 Camunda Platform 8 is built to handle three key aspects of process automation:
@@ -14,7 +14,7 @@ Camunda Platform 8 is built to handle three key aspects of process automation:
 - Automate
 - Improve
 
-A user can design process flows through our [Modeler](/components/modeler/about-modeler.md). In a production scenario, you can deploy through Desktop Modeler, Web Modeler, or programmatically. A user can use [Tasklist](/components/tasklist/introduction-to-tasklist.md) to review and complete tasks, and [Operate](/components/operate/operate-introduction.md) to view and analyze process instances.
+A user can design process flows through our [Modeler]($docs$/components/modeler/about-modeler/). In a production scenario, you can deploy through Desktop Modeler, Web Modeler, or programmatically. A user can use [Tasklist]($docs$/components/tasklist/introduction-to-tasklist/) to review and complete tasks, and [Operate]($docs$/components/operate/operate-introduction) to view and analyze process instances.
 
 Beyond these design and automate cornerstones lies an important component to leverage our process data and analyze areas for improvement: Optimize.