docs: add getting-started and rename Basics to Overview (#5100)

* chore: rename Basics/basics to Overview/overview * feat: add Getting Started section To minimize rebasing after acceptance, I've pulled in introducing a Getting Started section to this PR. * fix: docs gen Incorporate changes from `generate-docs` * fix: redirects Ensure past redirects continue to work. * chore: redirect `kubernetes.ts` docs link * chore: set proper links to docs pages * chore: move installation.md * Temporarily disable docs check * chore: temporarily disable docs check * test: fix test assertions --------- Co-authored-by: Anna Mager <[email protected]> Co-authored-by: Vladimir Vagaytsev <[email protected]>
garden-io · Sep 19, 2023 · b03ada9 · b03ada9
1 parent 640b51a
commit b03ada9
Show file tree

Hide file tree

Showing 49 changed files with 107 additions and 92 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -902,8 +902,8 @@ workflows:
           requires: [build]
       - lint:
           requires: [build]
-      - check-docs:
-          requires: [build]
+      # - check-docs:
+      #     requires: [build]
       - check-package-licenses:
           requires: [build]
       - test-framework:

diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -5,10 +5,10 @@ structure:
   summary: README.md
 
 redirects:
-  installation: ./getting-started/1-installation.md
-  quick-start: ./getting-started/0-introduction.md
-  basics/installation: ./getting-started/1-installation.md
-  stack-graph: ./basics/stack-graph.md
+  installation: ./getting-started/installation.md
+  quick-start: ./getting-started/quickstart.md
+  basics/installation: ./getting-started/installation.md
+  stack-graph: ./overview/stack-graph.md
   troubleshooting: ./misc/troubleshooting.md
   examples/demo-project: ./example-projects/demo-project.md
   examples/tls-project: ./example-projects/tls-project.md
@@ -18,7 +18,7 @@ redirects:
   providers/conftest-container: ./reference/providers/conftest-container.md
   providers/conftest-kubernetes: ./reference/providers/conftest-kubernetes.md
   providers/conftest: ./reference/providers/conftest.md
-  providers/hadolint: ./reference/providers/hadolint.md
+  providers/hadolint: ./reference/providers/hadolint.md♡
   providers/kubernetes: ./reference/providers/kubernetes.md
   providers/local-kubernetes: ./reference/providers/local-kubernetes.md
   providers/maven-container: ./reference/providers/maven-container.md
@@ -41,10 +41,10 @@ redirects:
   advanced/pulumi: ./pulumi-plugin/about.md
   advanced/rbac-config: ./k8s-plugins/advanced/rbac-config.md
   getting-started: ./tutorials/your-first-project.md
-  getting-started/0-introduction: ./basics/quickstart
-  getting-started/1-installation: ./guides/installation.md
+  getting-started/0-introduction: ./overview/quickstart
+  getting-started/1-installation: ./getting-started/installation.md
   getting-started/2-connect-to-a-cluster: ./tutorials/your-first-project/2-connect-to-a-cluster.md
-  basics/5-min-quickstart: ./basics/quickstart.md
+  basics/5-min-quickstart: ./getting-started/quickstart.md
   other-plugins/container: ./other-plugins/container
   guides/remote-kubernetes: ./k8s-plugins/about.md
   guides/in-cluster-building: ./k8s-plugins/advanced/in-cluster-building.md

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ _If you love Garden, please ★ star this repository to show your support :green
   <img src="https://github.com/garden-io/garden/assets/59834693/f62a04cb-44bc-4dd4-8426-398b6cd846fd" align="center">
 </p>
 <div align="center">
-  <a href="https://docs.garden.io/basics/5-min-quickstart/?utm_source=github">Quickstart</a>
+  <a href="https://docs.garden.io/getting-started/quickstart/?utm_source=github">Quickstart</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://garden.io/?utm_source=github">Website</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
@@ -30,15 +30,15 @@ With Garden you can:
 
 ## Installation
 
-The fastest way to get started with Garden is by following our [quickstart guide](https://docs.garden.io/basics/quickstart).
+The fastest way to get started with Garden is by following our [quickstart guide](https://docs.garden.io/getting-started/quickstart).
 
 Otherwise:
 
 ```sh
 curl -sL https://get.garden.io/install.sh | bash
 ```
 
-For more installation options, see the [installation guide](https://docs.garden.io/basics/quickstart#step-1-install-garden).
+For more installation options, see the [installation guide](https://docs.garden.io/getting-started/installation).
 
 ## Demo
 
@@ -124,7 +124,7 @@ The Stack Graph is a key feature of Garden that enables efficient development, t
 
 For more information on the Stack Graph and how Garden works, see:
 
-- [How Garden Works](https://docs.garden.io/basics/how-garden-works)
+- [How Garden Works](https://docs.garden.io/overview/how-garden-works)
 - [A video tour of the Stack Graph and guide to getting started](https://www.youtube.com/watch?app=desktop&v=3gMJWGV0WE8)
 
 ## Plugins

diff --git a/core/src/plugins/kubernetes/ephemeral/ephemeral.ts b/core/src/plugins/kubernetes/ephemeral/ephemeral.ts
@@ -35,7 +35,7 @@ export const gardenPlugin = () =>
 
     The \`${EPHEMERAL_KUBERNETES_PROVIDER_NAME}\` provider is a specialized version of the [\`kubernetes\` provider](${providerUrl}) that allows to deploy applications to one of the ephemeral Kubernetes clusters provided by Garden.
 
-    For information about using ephemeral Kubernetes clusters, please refer to [Ephemeral Kubernetes clusters guide](../../guides/ephemeral-clusters.md)
+    For information about using ephemeral Kubernetes clusters, please refer to [Ephemeral Kubernetes clusters guide](../../overview/ephemeral-clusters.md)
   `,
     configSchema: configSchema(),
     outputsSchema,

diff --git a/core/src/plugins/kubernetes/kubernetes.ts b/core/src/plugins/kubernetes/kubernetes.ts
@@ -149,7 +149,7 @@ export const gardenPlugin = () => {
 
     For usage information, please refer to the [guides section](../../guides). A good place to start is
     the [Remote Kubernetes guide](${makeDocsLink`k8s-plugins/remote-k8s/README`}) guide if you're connecting to remote clusters.
-    The [Quickstart guide](${makeDocsLink`basics/quickstart`}) guide is also helpful as an introduction.
+    The [Quickstart guide](${makeDocsLink`getting-started/quickstart`}) guide is also helpful as an introduction.
 
     Note that if you're using a local Kubernetes cluster (e.g. minikube or Docker Desktop), the [local-kubernetes provider](./local-kubernetes.md) simplifies (and automates) the configuration and setup quite a bit.
   `,

diff --git a/core/src/plugins/kubernetes/local/local.ts b/core/src/plugins/kubernetes/local/local.ts
@@ -20,7 +20,7 @@ export const gardenPlugin = () =>
     docs: dedent`
     The \`local-kubernetes\` provider is a specialized version of the [\`kubernetes\` provider](${providerUrl}) that automates and simplifies working with local Kubernetes clusters.
 
-    For general Kubernetes usage information, please refer to the [Kubernetes guides](${DOCS_BASE_URL}/kubernetes-plugins/about). For local clusters a good place to start is the [Local Kubernetes](${DOCS_BASE_URL}/kubernetes-plugins/local-k8s) guide. The [Quickstart Guide](${DOCS_BASE_URL}/basics/quickstart) guide is also helpful as an introduction.
+    For general Kubernetes usage information, please refer to the [Kubernetes guides](${DOCS_BASE_URL}/kubernetes-plugins/about). For local clusters a good place to start is the [Local Kubernetes](${DOCS_BASE_URL}/kubernetes-plugins/local-k8s) guide. The [Quickstart Guide](${DOCS_BASE_URL}/overview/quickstart) guide is also helpful as an introduction.
 
     If you're working with a remote Kubernetes cluster, please refer to the [\`kubernetes\` provider](${providerUrl}) docs, and the [Remote Kubernetes guide](${DOCS_BASE_URL}/kubernetes-plugins/remote-k8s) guide.
   `,

diff --git a/core/src/util/validateInstall.ts b/core/src/util/validateInstall.ts
@@ -24,7 +24,7 @@ function versionCheckError(params: BinaryVersionCheckParams, msg: string): Runti
     message: deline`
       ${msg}
       Please make sure ${params.name} (version ${params.minVersion} or later) is installed and on your PATH.
-      More about garden installation and requirements can be found in our documentation at ${DOCS_BASE_URL}/guides/installation
+      More about garden installation and requirements can be found in our documentation at ${DOCS_BASE_URL}/getting-started/installation
       `,
   })
 }

diff --git a/core/test/unit/src/build-staging/build-staging.ts b/core/test/unit/src/build-staging/build-staging.ts
@@ -19,6 +19,7 @@ import { BuildStagingRsync, minRsyncVersion } from "../../../../src/build-stagin
 import { BuildTask } from "../../../../src/tasks/build"
 import { ConfigGraph } from "../../../../src/graph/config-graph"
 import { BuildAction } from "../../../../src/actions/build"
+import { DOCS_BASE_URL } from "../../../../src/constants"
 
 // TODO-G2: rename test cases to match the new graph model semantics
 
@@ -301,7 +302,7 @@ describe("BuildStagingRsync", () => {
         contains: [
           "found rsync binary but the version is too old",
           "please make sure rsync",
-          "more about garden installation and requirements can be found in our documentation",
+          `more about garden installation and requirements can be found in our documentation at ${DOCS_BASE_URL}/getting-started/installation`,
         ],
       })
     })
@@ -312,7 +313,7 @@ describe("BuildStagingRsync", () => {
         contains: [
           "could not detect rsync binary version in the version command",
           "please make sure rsync",
-          "more about garden installation and requirements can be found in our documentation",
+          `more about garden installation and requirements can be found in our documentation at ${DOCS_BASE_URL}/getting-started/installation`,
         ],
       })
     })

diff --git a/docs/README.md b/docs/README.md
@@ -2,24 +2,29 @@
 
 * [Welcome!](welcome.md)
 
-## 🌸 Basics
+## 🌸 Overview
 
-* [How Garden Works](./basics/how-garden-works.md)
-* [Quickstart Guide](./basics/quickstart.md)
-* [Core Concepts](./basics/core-concepts.md)
-* [Use Cases](./basics/use-cases.md)
-* [Adopting Garden](./basics/adopting-garden.md)
-* [Garden vs Other Tools](./basics/garden-vs-other-tools.md)
+* [How Garden Works](./overview/how-garden-works.md)
+* [Core Concepts](./overview/core-concepts.md)
+* [Use Cases](./overview/use-cases.md)
+* [Adopting Garden](./overview/adopting-garden.md)
+* [Garden vs Other Tools](./overview/garden-vs-other-tools.md)
 
-## 🌳 Tutorials
+## 🌳 Getting Started
+
+* [Quickstart Guide](./getting-started/quickstart.md)
+* [Interactive Playgrounds](./getting-started/interactive-playgrounds.md)
+* [Installing Garden](./getting-started/installation.md)
+
+## 🌻 Tutorials
 
 * [Your First Project](./tutorials/your-first-project/README.md)
   * [1. Initialize a Project](./tutorials/your-first-project/1-initialize-a-project.md)
   * [2. Connect to a Cluster](./tutorials/your-first-project/2-connect-to-a-cluster.md)
   * [3. Deploy and Test](./tutorials/your-first-project/3-deploy-and-test.md)
   * [4. Configure Your Project](./tutorials/your-first-project/4-configure-your-project.md)
 
-## 🌻 Using Garden
+## 💐 Using Garden
 
 * [Configuration Overview](./using-garden/configuration-overview.md)
 * [Projects](./using-garden/projects.md)
@@ -32,7 +37,7 @@
 * [Using the CLI](./using-garden/using-the-cli.md)
 * [Modules](./using-garden/modules.md)
 
-## 💐 Kubernetes Plugins
+## 🌿 Kubernetes Plugins
 
 * [About](./k8s-plugins/about.md)
 * [Remote K8s Plugin Configuration](./k8s-plugins/remote-k8s/README.md)
@@ -61,40 +66,39 @@
   * [Minimal RBAC Configuration for Development Clusters](./k8s-plugins/advanced/rbac-config.md)
   * [Deploying to Production](./k8s-plugins/advanced/deploying-to-production.md)
 
-## 🌿 Terraform Plugin
+## 🌺 Terraform Plugin
 
 * [About](./terraform-plugin/about.md)
 * [Plugin Configuration](./terraform-plugin/configure-provider.md)
 * [Action Configuration](./terraform-plugin/action-configuration.md)
 
-## 🌺 Pulumi Plugin
+## ☘️ Pulumi Plugin
 
 * [About](./pulumi-plugin/about.md)
 * [Plugin Configuration](./pulumi-plugin/configure-provider.md)
 * [Action Configuration](./pulumi-plugin/action-configuration.md)
 
-## ☘️ Other Plugins
+## 🌹 Other Plugins
 
 * [Container](./other-plugins/container.md)
 * [Exec (local scripts)](./other-plugins/exec.md)
 
-## 🌹 Guides
+## 🌼 Guides
 
 * [Migrating to Bonsai](./guides/migrating-to-bonsai.md)
-* [Installing Garden](./guides/installation.md)
-* [Connecting a local application to a Kubernetes cluster (Local Mode)](./guides/running-service-in-local-mode.md)
-* [Code Synchronization](./guides/code-synchronization.md)
 * [Environments and namespaces](./guides/namespaces.md)
+* [Code Synchronization](./guides/code-synchronization.md)
+* [Connecting a local application to a Kubernetes cluster (Local Mode)](./guides/running-service-in-local-mode.md)
 * [Migrating from Docker Compose to Garden](./guides/migrating-from-docker-compose.md)
 * [Using Garden in CI](./guides/using-garden-in-ci.md)
 * [Ephemeral Kubernetes Clusters](./guides/ephemeral-clusters.md)
 
-## 🌼 Advanced
+## 🌷 Advanced
 
 * [Using Remote Sources](./advanced/using-remote-sources.md)
 * [Custom Commands](./advanced/custom-commands.md)
 
-## 🌷 Reference
+## 🪷 Reference
 
 * [Providers](./reference/providers/README.md)
   * [`conftest-container`](./reference/providers/conftest-container.md)
@@ -173,13 +177,13 @@
   * [`templated`](./reference/module-types/templated.md)
   * [`terraform`](./reference/module-types/terraform.md)
 
-## 🪷 Garden Seeds
+## 🎋 Garden Seeds
 
 * [About](./garden-seeds/about.md)
 * [Languages](./garden-seeds/languages/README.md)
   * [Go 🌸](./garden-seeds/languages/go.md)
 
-## 🎋 Misc
+## 🌸 Misc
 
 * [FAQ](./misc/faq.md)
 * [Troubleshooting](./misc/troubleshooting.md)

diff --git a/docs/advanced/README.md b/docs/advanced/README.md
@@ -1,4 +1,4 @@
 ---
-order: 9
+order: 10
 title: Advanced
 ---
diff --git a/docs/advanced/custom-commands.md b/docs/advanced/custom-commands.md
@@ -41,7 +41,7 @@ Before diving in, there are a few constraints and caveats to be aware of when de
 
 We may later lift some of these limitations. Please post a [GitHub issue](https://github.com/garden-io/garden/issues) if any of the above is getting in your way!
 
-## Basics
+## Overview
 
 Each command has to define a `name`, which must be a valid identifier (following the same rules as action names etc.). A short description must also be provided with `description.short`, and you can also provide a longer description on `description.long` which is shown when you run the command with `--help`. For example:
 

diff --git a/docs/garden-seeds/README.md b/docs/garden-seeds/README.md
@@ -1,4 +1,4 @@
 ---
 title: Garden Seeds
-order: 11
+order: 12
 ---
diff --git a/docs/garden-seeds/languages/go.md b/docs/garden-seeds/languages/go.md
@@ -18,7 +18,7 @@ This demo scaffolds a Helm chart we'll deploy to our Kubernetes cluster.
 
 ## Prerequisites
 
-1. Install Garden CLI and get a Kubernetes cluster running locally by following our [quickstart guide](https://docs.garden.io/basics/quickstart) 🔎.
+1. Install Garden CLI and get a Kubernetes cluster running locally by following our [quickstart guide](https://docs.garden.io/overview/quickstart) 🔎.
 2. Ensure Python is available on your system and version 3.7 or higher by running `python --version`. MacOS and most Linux distributions will have Python already installed. Follow the official Python installation [guide](https://docs.python-guide.org/starting/installation/#installation-guides) if not. Python is required to scaffold the language seed.
 3. If  any of the terminology is unfamiliar, don't hesitate to contact our Community Engineering team over on [Discord](https://go.garden.io/discord) 💭.
 
@@ -80,7 +80,7 @@ Continue your Garden Journey. If you wish to learn more about Garden, here are a
 
 - Join our beautiful community on [Discord](https://go.garden.io/discord) 👋🏻.
 - Give us a star in our [main repository](https://github.com/garden-io/garden) to show your support 💚.
-- Read the [How Garden Works](https://docs.garden.io/basics/how-garden-works) page to understand the core concepts behind Garden.
+- Read the [How Garden Works](https://docs.garden.io/overview/how-garden-works) page to understand the core concepts behind Garden.
 - Read the [Helm Action configuration](https://docs.garden.io/reference/action-types/deploy/helm) document to extend your Helm configuration within your new project.
 - Extend your configuration by using a [Remote K8s environment](https://docs.garden.io/kubernetes-plugins/remote-k8s).
 

diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
@@ -0,0 +1,5 @@
+---
+order: 2
+title: Getting Started
+---
+
diff --git a/docs/guides/installation.md → docs/getting-started/installation.md b/docs/guides/installation.md → docs/getting-started/installation.md
@@ -1,6 +1,6 @@
 ---
 title: Installing Garden
-order: 2
+order: 3
 ---
 
 # Installing Garden

diff --git a/docs/getting-started/interactive-playgrounds.md b/docs/getting-started/interactive-playgrounds.md
@@ -0,0 +1,14 @@
+---
+title: Interactive Playgrounds
+order: 2
+---
+
+# Interactive environments
+
+Preview Garden with our new interactive and install-free cloud-based playgrounds ✨.
+
+Click a button to start your Killercoda or Google Cloud Shell environment 👇🏼.
+
+<a href="https://go.garden.io/killercoda"><img src="https://raw.githubusercontent.com/garden-io/garden-interactive-environments/main/resources/img/killercoda-54px.png" alt="Killercoda logo in black and white." height="54px"></a> [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://go.garden.io/cloudshell)
+
+If you find any bugs 🐛 or have suggestions to improve our labs please don't hesitate to reach out by creating an [issue here](https://github.com/garden-io/garden-interactive-environments) or by asking in our [Discord Community](https://go.garden.io/discord)🌸
diff --git a/docs/basics/quickstart.md → docs/getting-started/quickstart.md b/docs/basics/quickstart.md → docs/getting-started/quickstart.md
@@ -1,6 +1,6 @@
 ---
 title: Quickstart Guide
-order: 2
+order: 1
 ---
 
 # Quickstart Guide
@@ -11,16 +11,6 @@ A visual quickstart is also available by logging in to the Garden Dashboard. The
 
 Garden is an all-in-one DevOps platform that enables you to build, test, deploy your applications and infrastructure in a single, unified workflow.
 
-## Interactive environments
-
-Preview Garden with our new interactive and install-free cloud-based playgrounds ✨.
-
-Click a button to start your Killercoda or Google Cloud Shell environment 👇🏼.
-
-<a href="https://go.garden.io/killercoda"><img src="https://raw.githubusercontent.com/garden-io/garden-interactive-environments/main/resources/img/killercoda-54px.png" alt="Killercoda logo in black and white." height="54px"></a> [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://go.garden.io/cloudshell)
-
-If you find any bugs 🐛 or have suggestions to improve our labs please don't hesitate to reach out by creating an [issue here](https://github.com/garden-io/garden-interactive-environments) or by asking in our [Discord Community](https://go.garden.io/discord)🌸
-
 ## Quickstart
 
 In this quickstart, we'll introduce you to the one interactive command you'll spend most of your time in as a developer: `garden dev`.

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -1,4 +1,4 @@
 ---
-order: 8
+order: 9
 title: Guides
 ---
diff --git a/docs/guides/ephemeral-clusters.md b/docs/guides/ephemeral-clusters.md
@@ -17,10 +17,11 @@ You can add or remove ephemeral Kubernetes cluster easily via the `ephemeral-kub
 
 ## Getting started
 
-There are multiple example garden projects that are already configured and ready to go with Garden ephemeral clusters. Checkout our [quickstart guide](../basics/quickstart.md) or the [ephemeral-cluster-demo](https://github.com/garden-io/garden/tree/main/examples/ephemeral-cluster-demo) example on GitHub.
+There are multiple example garden projects that are already configured and ready to go with Garden ephemeral clusters. Checkout our [quickstart guide](../getting-started/quickstart.md) or the [ephemeral-cluster-demo](https://github.com/garden-io/garden/tree/main/examples/ephemeral-cluster-demo) example on GitHub.
 In the following steps you'll learn how to configure your own Garden projects to use the `ephemeral-kubernetes` provider.
 
 ### Step 1 - Configure the provider
+
  Add the `ephemeral-kubernetes` provider to your project configuration file and associate it with an environment. If you are starting a new project copy this file:
 
 ```yaml

diff --git a/docs/k8s-plugins/README.md b/docs/k8s-plugins/README.md
@@ -1,4 +1,4 @@
 ---
 title: Kubernetes Plugins
-order: 4
+order: 5
 ---
diff --git a/docs/k8s-plugins/action-types/container.md b/docs/k8s-plugins/action-types/container.md
@@ -57,7 +57,7 @@ spec:
 ...
 ```
 
-`env` is a simple mapping of "name: value". [Template strings](../../using-garden/variables-and-templating.md#template-string-basics) can also be used to interpolate values.
+`env` is a simple mapping of "name: value". [Template strings](../../using-garden/variables-and-templating.md#template-string-overview) can also be used to interpolate values.
 
 ### Secrets
 

diff --git a/docs/misc/README.md b/docs/misc/README.md
@@ -3,7 +3,7 @@ title: Misc
 order: 99
 ---
 
-# Basics
+# Overview
 
 * [Troubleshooting](./troubleshooting.md)
 * [Telemetry](./telemetry.md)
-Original file line number
+Diff line change
@@ Expand Up / @@ -57,7 +57,7 @@ spec: @@
     ...
     ```
-    `env` is a simple mapping of "name: value". [Template strings](../../using-garden/variables-and-templating.md#template-string-basics) can also be used to interpolate values.
+    `env` is a simple mapping of "name: value". [Template strings](../../using-garden/variables-and-templating.md#template-string-overview) can also be used to interpolate values.
     ### Secrets
@@ Expand Down @@