From 9c7eadded0931f1079f53ea2e7e8711b824fc92c Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Tue, 4 Jul 2023 14:19:34 +0200
Subject: [PATCH] docs: switch order of api doc sidebar items; put legacy docs
 under legacy header (#4135)

Also adds a caution admonition to the legacy doc index page
---
 .../reference/api/legacy/unleash/index.md     |  8 ++-
 website/sidebars.js                           | 68 ++++++++++---------
 2 files changed, 44 insertions(+), 32 deletions(-)

diff --git a/website/docs/reference/api/legacy/unleash/index.md b/website/docs/reference/api/legacy/unleash/index.md
index 8ddcb4cf30..c36a5d275a 100644
--- a/website/docs/reference/api/legacy/unleash/index.md
+++ b/website/docs/reference/api/legacy/unleash/index.md
@@ -1,8 +1,14 @@
 ---
 id: index
-title: API Documentation
+title: Legacy API Documentation
 ---
 
+:::caution
+
+The docs in this category are legacy documentation. You should prefer to use the [Unleash OpenAPI docs](/reference/api/unleash) instead whenever possible.
+
+:::
+
 ## Client API {#client-api}
 
 This describes the API provided to unleash-clients.
diff --git a/website/sidebars.js b/website/sidebars.js
index 56d876858d..fbf355f803 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -181,39 +181,8 @@ module.exports = {
                 },
                 {
                     type: 'category',
-                    link: {
-                        type: 'doc',
-                        id: 'reference/api/legacy/unleash/index',
-                    },
                     label: 'APIs',
                     items: [
-                        {
-                            'Admin API': [
-                                'reference/api/legacy/unleash/admin/addons',
-                                'reference/api/legacy/unleash/admin/context',
-                                'reference/api/legacy/unleash/admin/events',
-                                'reference/api/legacy/unleash/admin/features-v2',
-                                'reference/api/legacy/unleash/admin/feature-types',
-                                'reference/api/legacy/unleash/admin/features',
-                                'reference/api/legacy/unleash/admin/archive',
-                                'reference/api/legacy/unleash/admin/metrics',
-                                'reference/api/legacy/unleash/admin/projects',
-                                'reference/api/legacy/unleash/admin/segments',
-                                'reference/api/legacy/unleash/admin/state',
-                                'reference/api/legacy/unleash/admin/strategies',
-                                'reference/api/legacy/unleash/admin/tags',
-                                'reference/api/legacy/unleash/admin/user-admin',
-                            ],
-                            'Client API': [
-                                'reference/api/legacy/unleash/client/features',
-                                'reference/api/legacy/unleash/client/metrics',
-                                'reference/api/legacy/unleash/client/register',
-                            ],
-                            'System API': [
-                                'reference/api/legacy/unleash/internal/prometheus',
-                                'reference/api/legacy/unleash/internal/health',
-                            ],
-                        },
                         {
                             label: 'OpenAPI docs',
                             collapsed: true,
@@ -227,6 +196,43 @@ module.exports = {
                             },
                             items: require('./docs/reference/api/unleash/sidebar.js'),
                         },
+                        {
+                            type: 'category',
+                            label: 'Legacy API docs',
+                            link: {
+                                type: 'doc',
+                                id: 'reference/api/legacy/unleash/index',
+                            },
+                            items: [
+                                {
+                                    'Admin API': [
+                                        'reference/api/legacy/unleash/admin/addons',
+                                        'reference/api/legacy/unleash/admin/context',
+                                        'reference/api/legacy/unleash/admin/events',
+                                        'reference/api/legacy/unleash/admin/features-v2',
+                                        'reference/api/legacy/unleash/admin/feature-types',
+                                        'reference/api/legacy/unleash/admin/features',
+                                        'reference/api/legacy/unleash/admin/archive',
+                                        'reference/api/legacy/unleash/admin/metrics',
+                                        'reference/api/legacy/unleash/admin/projects',
+                                        'reference/api/legacy/unleash/admin/segments',
+                                        'reference/api/legacy/unleash/admin/state',
+                                        'reference/api/legacy/unleash/admin/strategies',
+                                        'reference/api/legacy/unleash/admin/tags',
+                                        'reference/api/legacy/unleash/admin/user-admin',
+                                    ],
+                                    'Client API': [
+                                        'reference/api/legacy/unleash/client/features',
+                                        'reference/api/legacy/unleash/client/metrics',
+                                        'reference/api/legacy/unleash/client/register',
+                                    ],
+                                    'System API': [
+                                        'reference/api/legacy/unleash/internal/prometheus',
+                                        'reference/api/legacy/unleash/internal/health',
+                                    ],
+                                },
+                            ],
+                        },
                     ],
                 },
                 {