Docusaurus v3 (#8485)

- Upgrades to latest Docusaurus
- Upgrades our OpenAPI plugin to latest too
- Removes old, unneeded dependencies
- Our configs and sidebar files now use TypeScript

[Preview
link](https://unleash-docs-git-alvin-docusaurus-v3-unleash-team.vercel.app/)

---------

Co-authored-by: melindafekete <[email protected]>
Co-authored-by: Christopher Kolstad <[email protected]>

.gitignore

@@ -58,7 +58,7 @@ frontend/src/openapi/apis
 frontend/src/openapi/index.ts
 
 # Generated docs
-website/docs/reference/api/**/sidebar.js
+website/docs/reference/api/**/sidebar.ts
 website/docs/reference/api/**/**.info.mdx
 website/docs/generated
 reports/jest-junit.xml

website/.gitignore

@@ -20,7 +20,7 @@ yarn-debug.log*
 yarn-error.log*
 
 # OpenAPI docusaurus generated stuff
-docs/reference/api/**/sidebar.js
+docs/reference/api/**/sidebar.ts
 *.api.mdx
 *.tag.mdx
 

website/clean-generated-docs.js → website/clean-generated-docs.mjs

@@ -15,7 +15,7 @@
 // the bits that are specific to the generation source we use, and make the docs
 // easier to use. In particular, removing the leading `/ushosted` is likely to
 // save us loooots of questions.
-const replace = require('replace-in-file');
+import { replaceInFileSync } from 'replace-in-file';
 
 const options = {
     files: 'docs/reference/api/**/*.api.mdx',
@@ -27,4 +27,4 @@ const options = {
     to: ['', '"<your-unleash-url>"', '"path":['],
 };
 
-replace(options);
+replaceInFileSync(options);

website/docs/feature-flag-tutorials/ios/implementing-feature-flags.md → website/docs/feature-flag-tutorials/ios/implementing-feature-flags-ios.md

@@ -13,12 +13,14 @@ In this tutorial, you will learn how to set up and use iOS feature flags with Un
 
 Here are the steps we will cover in this tutorial:
 
-1. [Feature flag best practices for client-side apps](#1-architect-to-limit-pii-and-configuration-leakage)
-2. [Spin up a local provider](#2-install-a-local-feature-flag-provider)
-3. [Configure a feature flag](#3-create-and-configure-the-feature-flag)
-4. [Add Unleash to an iOS app](#4-add-unleash-to-an-ios-app)
-5. [Log status of iOS feature flag](#5-configure-unleash-and-log-ios-feature-flag-status)
-6. [Verify the feature flag experience](#6-verify-the-feature-flag-experience)
+- [Prerequisites](#prerequisites)
+- [1. Architect to limit PII and configuration leakage](#1-architect-to-limit-pii-and-configuration-leakage)
+- [2. Install a local feature flag provider](#2-install-a-local-feature-flag-provider)
+- [3. Create and configure the feature flag](#3-create-and-configure-the-feature-flag)
+- [4. Add Unleash to an iOS app](#4-add-unleash-to-an-ios-app)
+- [5. Configure Unleash and log iOS feature flag status](#5-configure-unleash-and-log-ios-feature-flag-status)
+- [6. Verify the feature flag experience](#6-verify-the-feature-flag-experience)
+- [Conclusion](#conclusion)
 
 ## Prerequisites
 
@@ -37,7 +39,7 @@ a. Limit PII (personally identifiable information) leakage from the end-user dev
 
 b. Avoid leakage of configuration information from the central feature flag control service to end-user devices.
 
-Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/never-expose-pii).
+Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#2-protect-pii-by-evaluating-flags-server-side).
 
 ![Keep configurations and PII secure image](/img/react-tutorial-pii-diagram.png)
 

website/docs/feature-flag-tutorials/react/implementing-feature-flags.mdx

@@ -50,7 +50,7 @@ a. Limit PII (personally identifiable information) leakage from the end-user dev
 
 b. Avoid leakage of configuration information from the central feature flag control service to end-user devices.
 
-Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/never-expose-pii).
+Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#2-protect-pii-by-evaluating-flags-server-side).
 
 ![Keep configurations and PII secure image](/img/react-tutorial-pii-diagram.png)
 

website/docs/how-to/how-to-add-sso-azure-saml.mdx

@@ -76,7 +76,7 @@ To find your Microsoft Entra identifier, go to the single sign-on settings of yo
 
 To finalize the configuration, do the following:
 
-1. In the Unleash Admin UI, go to **Admin > Single sign-on> SAML 2.0**.
+1. In the Unleash Admin UI, go to **Admin > Single sign-on > SAML 2.0**.
 2. In **Entity ID**, enter your [Microsoft Entra identifier](#microsoft-entra-identifier).
 3. In **Single sign-on URL**, enter your [Login URL](#login-url).
 4. In **X.509 Certificate**, [enter your SAML certificate](#saml-certificate).

website/docs/how-to/how-to-environment-import-export.mdx

@@ -1,7 +1,10 @@
 ---
 title: Environment Import & Export
 ---
+
+
 import VideoContent from '@site/src/components/VideoContent.jsx'
+import Figure from '@site/src/components/Figure/Figure.tsx'
 
 :::note Availability
 

website/docs/reference/feature-toggles.mdx

@@ -71,7 +71,7 @@ Marking a flag as stale helps you deprecate a feature flag without removing the
 
 You can use this to signal to your team to stop using the feature in your applications. Stale flags will show as stale in the [technical debt dashboard](./technical-debt).
 
-Marking a flag as stale generates the `feature-stale-on` [event](./reference/events#feature-stale-on). You can use [an integration](/integrations/integrations) to trigger automated workflows, such as posting notifications in a Slack channel, breaking project builds if the code contains stale flags, or automatically opening pull requests to remove stale flags from the code.
+Marking a flag as stale generates the `feature-stale-on` [event](/reference/events#feature-stale-on). You can use [an integration](/reference/integrations) to trigger automated workflows, such as posting notifications in a Slack channel, breaking project builds if the code contains stale flags, or automatically opening pull requests to remove stale flags from the code.
 
 ### Configure expected lifetime
 

website/docs/reference/integrations/jira-server-plugin-installation.md

@@ -70,7 +70,7 @@ server configured for a specific Jira project.
 
 ![A table marked Unleash Server Configuration, listing Unleash server instances.](/img/jira_server_manage_servers.png)
 
-Once you have configured at least one Unleash server, your users should be ready to [use the Jira Server plugin](/integrations/jira_server_plugin_usage)
+Once you have configured at least one Unleash server, your users should be ready to [use the Jira Server plugin](/reference/integrations/jira-server-plugin-usage)
 
 ### Edit existing servers
 

website/docs/reference/network-view.mdx

@@ -77,14 +77,7 @@ The `PROMETHEUS_API` environment variable should point to the base path of the P
 
 This setup means that there is a mutual dependency between Unleash and Prometheus, where Prometheus regularly fetches data from Unleash's backstage API and Unleash fetches and displays this data when you use the network view. This diagram provides a visual representation of that.
 
-```mermaid
-sequenceDiagram
-    participant Unleash
-    loop Scrape data
-    Prometheus-->>Unleash: fetch internal-backstage/prometheus
-    end
-    Unleash->>+Prometheus: Query data for network view
-```
+![](/img/network-view.png)
 
 
 [^1]: For instance: when using Unleash in an API setting, a common mistake is to instantiate a new SDK for every request instead of sharing a single instance across requests. This would be visible in the network overview graph as a large number of requests from the same app.

website/docs/reference/sdks/index.mdx

@@ -55,7 +55,6 @@ If you see an item marked with a ❌ that you would find useful, feel free to re
 
 :::
 
-<!-- prettier-ignore-start -->
 
 | Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
 | --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
@@ -89,7 +88,7 @@ If you see an item marked with a ❌ that you would find useful, feel free to re
 | Static fields (`environment`, `appName`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Defined fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Custom properties | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Category: [`isEnabled`](./client-specification#implementation-of-isenabled)** |  |  |  |  |  |  |  |  |
+| **Category: [`isEnabled`](/client-specification#implementation-of-isenabled)** |  |  |  |  |  |  |  |  |
 | Can take context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Override fallback value | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Fallback function | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ |
@@ -110,7 +109,6 @@ If you see an item marked with a ❌ that you would find useful, feel free to re
 | Bootstrap from file | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
 | Custom Bootstrap implementation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
 
-<!-- prettier-ignore-end -->
 
 ## Community SDKs ❤️ {#community-sdks}
 
@@ -138,7 +136,7 @@ Here's some of the fantastic work our community has done to make Unleash work in
 If you can't find an SDK that fits your requirements, you can also develop your own SDK. To make implementation easier, check out these resources:
 
 -   [Unleash Client Specifications](https://github.com/Unleash/client-specification) - Used by all official SDKs to make sure they behave correctly across different language implementations. This lets us verify that a gradual rollout to 10% of the users would affect the same users regardless of which SDK you're using.
--   [Client SDK overview](./client-specification) - A brief, overall guide of the _Unleash Architecture_ and important aspects of the SDK role in it all.
+-   [Client SDK overview](/client-specification) - A brief, overall guide of the _Unleash Architecture_ and important aspects of the SDK role in it all.
 
 ## Client-side SDK behavior
 

website/docs/reference/segments.mdx

@@ -52,7 +52,7 @@ In theory, you could create segments with a thousand constraints, each with a mi
 
 By default, you can apply **at most 5 segments to any one strategy**. Separate strategies (even on the same feature) do not count towards the same total, so you can have two strategies with 5 segments each.
 
-You **can** [configure segment limits](./using-unleash/deploy/configuring-unleash#segments) with environment variables.
+You **can** [configure segment limits](/using-unleash/deploy/configuring-unleash#segments) with environment variables.
 
 ### A note on large segments {#large-segments}
 

website/docs/understanding-unleash/unleash-overview.md

@@ -23,7 +23,7 @@ Before you can connect your application to Unleash you need a Unleash server. Yo
 ![A visual overview of an Unleash system as described in the following paragraph.](/img/unleash-architecture-edge.png 'System Overview')
 
 - [**Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature flags, configure activation strategies, and parameters, etc. The service that contains all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
-- **Unleash Admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](/how-to-create-feature-flag), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles), [create API tokens](how-to/how-to-create-api-tokens), and more.
+- **Unleash Admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](/how-to-create-feature-flag), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles), [create API tokens](../how-to/how-to-create-api-tokens), and more.
 - [**Unleash SDKs**](../reference/sdks) - Unleash SDKs integrate into your applications and get feature configurations from the Unleash API. Use them to check whether features are enabled or disabled and to send metrics to the Unleash API. [See all our SDKs](../reference/sdks)
 - [**Unleash Edge**](../reference/unleash-edge) - The Unleash Edge sits between front-end and native applications on one side and the Unleash API on the other. It can also sit between server-side SDKs and the Unleash API as well. You can scale it independently of the Unleash API to handle large request rates without causing issues for the Unleash API. Edge has all endpoints for the client API, frontend API, and proxy API. 
 

website/docs/using-unleash/deploy/upgrading-unleash.mdx

@@ -144,8 +144,6 @@ As such, if you're relying on the specifics of the error structure for those API
 
 Before you upgrade we strongly recommend that you take a full [database backup](database-backup), to make sure you can downgrade to version 3.
 
-You can also read the highlights of **[what's new in v4](/user_guide/v4-whats-new)**.
-
 ### 1. All API calls now require a token. {#1-all-api-calls-now-requires-token}
 
 If you are upgrading from Unleash Open-Source v3 client SDKs did not need to use an API token in order to connect to Unleash-server. Starting from v4 we have back-ported the API token handling for Enterprise in to the Open-Source version. This means that all client SDKs now need to use a client token in order to connect to Unleash.

website/docusaurus.config.js → website/docusaurus.config.ts

@@ -1,5 +1,8 @@
-const { sdks } = require('./remote-content/sdks');
-const { docs: edgeAndProxy } = require('./remote-content/edge-proxy');
+import type { Config } from '@docusaurus/types';
+
+import { sdks } from './remote-content/sdks';
+import { docs as edgeAndProxy } from './remote-content/edge-proxy';
+import pluginNpm2Yarn from '@docusaurus/remark-plugin-npm2yarn';
 
 // for a given redirect object, modify it's `from` property such that for every
 // path that doesn't start with `/docs/`, a corresponding path that _does_ start
@@ -38,8 +41,8 @@ const addDocsRoutePrefix = ({ from, ...rest }) => {
         from: addDocs(from),
     };
 };
-/** @type {import('@docusaurus/types').DocusaurusConfig} */
-module.exports = {
+
+const config: Config = {
     title: 'Unleash Documentation',
     tagline: 'The enterprise ready feature flag service',
     url: 'https://docs.getunleash.io',
@@ -50,7 +53,6 @@ module.exports = {
     organizationName: 'Unleash', // Usually your GitHub org/user name.
     projectName: 'unleash.github.io', // Usually your repo name.
     trailingSlash: false,
-    markdown: { mermaid: true },
     customFields: {
         // expose env vars etc here
         environment: process.env.NODE_ENV,
@@ -170,17 +172,13 @@ module.exports = {
             ],
         },
         prism: {
-            theme: require('prism-react-renderer/themes/oceanicNext'),
             additionalLanguages: [
                 'csharp',
                 'dart',
-                'http',
                 'java',
-                'kotlin',
                 'php',
                 'ruby',
-                'rust',
-                'swift',
+                'bash',
             ],
         },
         languageTabs: [
@@ -290,22 +288,16 @@ module.exports = {
             '@docusaurus/preset-classic',
             {
                 docs: {
-                    sidebarPath: require.resolve('./sidebars.js'),
                     // Please change this to your repo.
                     editUrl:
                         'https://github.com/Unleash/unleash/edit/main/website/',
                     routeBasePath: '/',
-                    remarkPlugins: [
-                        [
-                            require('@docusaurus/remark-plugin-npm2yarn'),
-                            { sync: true },
-                        ],
-                    ],
-                    docLayoutComponent: '@theme/DocPage',
+                    remarkPlugins: [[pluginNpm2Yarn, { sync: true }]],
                     docItemComponent: '@theme/ApiItem',
+                    sidebarPath: './sidebars.ts',
                 },
                 theme: {
-                    customCss: require.resolve('./src/css/custom.css'),
+                    customCss: './src/css/custom.css',
                 },
                 googleAnalytics: {
                     trackingID: 'UA-134882379-1',
@@ -911,7 +903,6 @@ module.exports = {
     ],
     themes: [
         'docusaurus-theme-openapi-docs', // Allows use of @theme/ApiItem and other components
-        '@docusaurus/theme-mermaid',
     ],
     scripts: [
         {
@@ -924,5 +915,7 @@ module.exports = {
             defer: true,
         },
     ],
-    clientModules: [require.resolve('./global.js')],
+    clientModules: ['./global.js'],
 };
+
+export default config;