Reorganize the "Home" section of the docs

Fixes #13206 The organization of the "Home" section of the docs currently says little about its purpose, making it more difficult for new visitors to the docs to find content. I've proposed changing this to a "Get Started" section that includes content related to trying out Teleport and choosing an edition. (Re)move pages that are unrelated to getting started: - Rename the "Preview" section to "Releases" and move the Changelog there. The Preview section doesn't include preview content very often, and usually only includes the Upcoming Releases page. I think it makes sense to devote this section to releases. - Remove the Adopters page and redirect to the Teleport case studies page. The Adopters page receives close to no traffic and is infrequently updated, so keeping it risks giving users outdated information. - Remove the Production guide. Redirects currently make it impossible to navigate to this page. - Move the Digital Ocean guide to "/docs/setup/deployments", since other platform-specific deployment guides are also placed there. Organize content related to getting started with Teleport into "Try out Teleport" and "Deploy a Teleport Cluster" subsections: - Encourage new users to try a quick lab by including a new menu page with links to all of our Instruqt tracks and local demo environments. Move our demo environment guides into "getting-started/try-out-teleport" - Put all of our edition-specific Getting Started guides into one subsection, "getting-started/deploy-a-cluster". This means that the Linux Server guide is no longer the de facto entryway into Teleport, which can confuse Cloud and Enterprise users. The "Deploy a Cluster" subsection includes a menu page with a guide to different editions. - With these new subsections, there's not really a place anymore for the /getting-started.mdx page, so I have removed this.
gravitational · Jun 13, 2022 · 714099a · 714099a
1 parent c083518
commit 714099a
Show file tree

Hide file tree

Showing 30 changed files with 359 additions and 639 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -417,7 +417,7 @@ To learn more about configuring role-based access control for Database Access, c
 
 See [Reference](https://goteleport.com/teleport/docs/database-access/reference/) for an overview of Database Access related configuration and CLI commands.
 
-Finally, check out [Frequently Asked Questions](./database-access/faq.mdx).
+Finally, check out [Frequently Asked Questions](./docs/pages/database-access/faq.mdx).
 
 #### OSS RBAC
 
@@ -1192,18 +1192,18 @@ This is a minor Teleport release with a focus on new features and bug fixes.
 ### Improvements
 
 * Alpha: Enhanced Session Recording lets you know what's really happening during a Teleport Session. [#2948](https://github.com/gravitational/teleport/issues/2948)
-* Alpha: Workflows API lets admins escalate RBAC roles in response to user requests. [Read the docs](./enterprise/workflow). [#3006](https://github.com/gravitational/teleport/issues/3006)
-* Beta: Teleport provides HA Support using Firestore and Google Cloud Storage using Google Cloud Platform. [Read the docs](./setup/deployments/gcp.mdx). [#2821](https://github.com/gravitational/teleport/pull/2821)
-* Remote tctl execution is now possible. [Read the docs](./setup/reference/cli.mdx#tctl). [#1525](https://github.com/gravitational/teleport/issues/1525) [#2991](https://github.com/gravitational/teleport/issues/2991)
+* Alpha: Workflows API lets admins escalate RBAC roles in response to user requests. [Read the docs](./docs/pages/enterprise/workflow/index.mdx). [#3006](https://github.com/gravitational/teleport/issues/3006)
+* Beta: Teleport provides HA Support using Firestore and Google Cloud Storage using Google Cloud Platform. [Read the docs](./docs/pages/setup/deployments/gcp.mdx). [#2821](https://github.com/gravitational/teleport/pull/2821)
+* Remote tctl execution is now possible. [Read the docs](./docs/pages/setup/reference/cli.mdx#tctl). [#1525](https://github.com/gravitational/teleport/issues/1525) [#2991](https://github.com/gravitational/teleport/issues/2991)
 
 ### Fixes
 
 * Fixed issue in socks4 when rendering remote address [#3110](https://github.com/gravitational/teleport/issues/3110)
 
 ### Documentation
 
-* Adopting root/leaf terminology for trusted clusters. [Trusted cluster documentation](./setup/admin/trustedclusters.mdx).
-* Documented Teleport FedRAMP & FIPS Support. [FedRAMP & FIPS documentation](./enterprise/fedramp.mdx).
+* Adopting root/leaf terminology for trusted clusters. [Trusted cluster documentation](./docs/pages/setup/admin/trustedclusters.mdx).
+* Documented Teleport FedRAMP & FIPS Support. [FedRAMP & FIPS documentation](./docs/pages/enterprise/fedramp.mdx).
 
 ## 4.1.11
 
@@ -1434,7 +1434,7 @@ With this release of Teleport, we have built out the foundation to help Teleport
 
 ### Improvements
 
-* Teleport now support 10,000 remote connections to a single Teleport cluster. [Using our recommend hardware setup.](./setup/operations/scaling.mdx#hardware-recommendations)
+* Teleport now support 10,000 remote connections to a single Teleport cluster. [Using our recommend hardware setup.](./docs/pages/setup/operations/scaling.mdx#hardware-recommendations)
 * Added ability to delete node using `tctl rm`. [#2685](https://github.com/gravitational/teleport/pull/2685)
 * Output of `tsh ls` is now sorted by node name. [#2534](https://github.com/gravitational/teleport/pull/2534)
 
@@ -1918,7 +1918,7 @@ available Teleport clusters with ease.
 #### Configuration Changes
 
 * Role templates (depreciated in Teleport 2.3) were fully removed. We recommend
-  migrating to role variables which are documented [here](./access-controls/guides/role-templates.mdx)
+  migrating to role variables which are documented [here](./docs/pages/access-controls/guides/role-templates.mdx)
 
 * Resource names (like roles, connectors, trusted clusters) can no longer
   contain unicode or other special characters. Update the names of all user

diff --git a/docs/config.json b/docs/config.json
@@ -2,39 +2,45 @@
   "navigation": [
     {
       "icon": "stack",
-      "title": "Home",
+      "title": "Get Started",
       "entries": [
         {
           "title": "Introduction",
           "slug": "/"
         },
         {
-          "title": "Adopters",
-          "slug": "/adopters/"
+          "title": "Try out Teleport",
+          "slug": "/getting-started/try-out-teleport/",
+          "entries": [
+            {
+              "title": "Get Started in your Browser",
+              "slug": "/getting-started/try-out-teleport/browser-labs/"
+            },
+            {
+              "title": "Docker Compose Lab",
+              "slug": "/getting-started/try-out-teleport/docker-compose/"
+            },
+            {
+              "title": "Kubernetes Lab",
+              "slug": "/getting-started/try-out-teleport/local-kubernetes/"
+            }
+          ]
         },
         {
-          "title": "Getting Started",
-          "slug": "/getting-started/",
+          "title": "Deploy a Teleport Cluster",
+          "slug": "/getting-started/deploy-a-cluster/",
           "entries": [
             {
-              "title": "Linux Server",
-              "slug": "/getting-started/linux-server/",
-              "hideInScopes": [
-                "enterprise",
-                "cloud"
-              ]
+              "title": "Open Source Teleport",
+              "slug": "/getting-started/deploy-a-cluster/open-source/?scope=oss"
             },
             {
-              "title": "Docker Compose",
-              "slug": "/getting-started/docker-compose/"
+              "title": "Teleport Cloud",
+              "slug": "/getting-started/deploy-a-cluster/cloud/?scope=cloud"
             },
             {
-              "title": "DigitalOcean",
-              "slug": "/getting-started/digitalocean/",
-              "hideInScopes": [
-                "enterprise",
-                "cloud"
-              ]
+              "title": "Teleport Enterprise",
+              "slug": "/getting-started/deploy-a-cluster/enterprise/?scope=enterprise"
             }
           ]
         },
@@ -45,10 +51,6 @@
         {
           "title": "FAQ",
           "slug": "/faq/"
-        },
-        {
-          "title": "Changelog",
-          "slug": "/changelog/"
         }
       ]
     },
@@ -113,6 +115,11 @@
               "title": "IBM",
               "slug": "/setup/deployments/ibm/",
               "hideInScopes": "cloud"
+            },
+            {
+              "title": "Digital Ocean",
+              "slug": "/setup/deployments/digitalocean/",
+              "hideInScopes": ["enterprise", "cloud"]
             }
           ]
         },
@@ -735,11 +742,15 @@
     },
     {
       "icon": "wand",
-      "title": "Preview",
+      "title": "Releases",
       "entries": [
         {
           "title": "Upcoming Releases",
-          "slug": "/preview/upcoming-releases/"
+          "slug": "/releases/upcoming-releases/"
+        },
+        {
+            "title": "Changelog",
+            "slug": "/releases/changelog/"
         }
       ]
     },
@@ -1263,6 +1274,31 @@
       "source": "/application-access/guides/jwt/",
       "destination": "/application-access/jwt/",
       "permanent": true
+    },
+    {
+      "source": "/preview/upcoming-releases/",
+      "destination": "/releases/upcoming-releases/",
+      "permanent": true
+    },
+    {
+      "source": "/changelog/",
+      "destination": "/releases/changelog/",
+      "permanent": true
+    },
+    {
+      "source": "/adopters/",
+      "destination": "https://goteleport.com/case-study/",
+      "permanent": true
+    },
+    {
+      "source": "/getting-started/digitalocean/",
+      "destination": "/setup/deployments/digitalocean/",
+      "permanent": true
+    },
+    {
+      "source": "/getting-started/",
+      "destination": "/",
+      "permanent": true
     }
   ]
 }
diff --git a/docs/pages/adopters.mdx b/docs/pages/adopters.mdx
diff --git a/docs/pages/api/getting-started.mdx b/docs/pages/api/getting-started.mdx
@@ -17,7 +17,7 @@ Here are the steps we'll walkthrough:
 ## Prerequisites
 
 - Install [Go](https://golang.org/doc/install) (=teleport.golang=)+ and Go development environment.
-- Set up Teleport through one of our [getting started guides](../getting-started.mdx). You can also begin a [free trial](https://goteleport.com/signup/) of Teleport Cloud.
+- Set up Teleport through one of our [getting started guides](../getting-started/deploy-a-cluster.mdx). You can also begin a [free trial](https://goteleport.com/signup/) of Teleport Cloud.
 
 ## Step 1/3. Create a user
 

diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx
@@ -31,7 +31,7 @@ Let's connect to Grafana using Teleport Application Access in three steps:
 - A host where you will run the Teleport Application Service.
 
 <Admonition type="tip" title="Not yet a Teleport user?">
-If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../getting-started.mdx) or try our Teleport Application Access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). 
+If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../getting-started/deploy-a-cluster.mdx) or try our Teleport Application Access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). 
 </Admonition>
 
 We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.)

diff --git a/docs/pages/architecture/overview.mdx b/docs/pages/architecture/overview.mdx
@@ -97,7 +97,7 @@ steps are explained below the diagram.
   title="Tip"
 >
   In the diagram above we show each Teleport service separately for clarity, but Teleport services do not have to run on separate nodes.
-  Teleport can be run as a binary on a single-node cluster with no external storage backend. We demonstrate this minimal setup in the [Getting Started Guide](../getting-started.mdx).
+  Teleport can be run as a binary on a single-node cluster with no external storage backend. We demonstrate this minimal setup in our [Getting Started guides](../getting-started/deploy-a-cluster.mdx).
 </Admonition>
 
 ## Detailed architecture overview
@@ -242,8 +242,11 @@ You can learn more about `tctl` in the [CLI Reference](../setup/reference/cli.md
 
 ## Next steps
 
-- If you haven't already, read the [Getting Started Guide](../getting-started.mdx) to run a
-  minimal setup of Teleport yourself.
+- If you haven't already, read the
+  [Getting Started guide](../getting-started/deploy-a-cluster.mdx) to run a
+  minimal setup of Teleport yourself, or
+  [try out Teleport](../getting-started/try-out-teleport.mdx) without deploying
+  any infrastructure.
 - Set up Teleport for your team with the [Admin Guide](../setup/admin.mdx).
 
 Read the rest of the Architecture Guides: