docs: update ToC layout

.gitbook.yaml

@@ -1,3 +1,26 @@
 structure:
   readme: README.md
   summary: docs/README.md
+
+redirects:
+  guides/using-remote-sources: guides/advanced/using-remote-sources.md
+  guides/cert-manager-integration: guides/advanced/cert-manager-integration.md
+  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/kubernetes: reference/providers/kubernetes.md
+  providers/local-kubernetes: reference/providers/local-kubernetes.md
+  providers/maven-container: reference/providers/maven-container.md
+  providers/openfaas: reference/providers/openfaas.md
+  providers/terraform: reference/providers/terraform.md
+  module-types/conftest: reference/module-types/conftest.md
+  module-types/container: reference/module-types/container.md
+  module-types/exec: reference/module-types/exec.md
+  module-types/hadolint: reference/module-types/hadolint.md
+  module-types/helm: reference/module-types/helm.md
+  module-types/kubernetes: reference/module-types/kubernetes.md
+  module-types/maven-container: reference/module-types/maven-container.md
+  module-types/openfaas: reference/module-types/openfaas.md
+  module-types/persistentvolumeclaim: reference/module-types/persistentvolumeclaim.md
+  module-types/terraform: reference/module-types/terraform.md

docs/README.md

@@ -1,57 +1,71 @@
 # Table of Contents
 
-* [Installation](./installation.md)
-* [Quick Start](./quick-start.md)
-* [Stack Graph](./stack-graph.md)
-* [Using Garden](./using-garden/README.md)
-  * [Creating a Project](./using-garden/creating-a-project.md)
-  * [Adding Modules](./using-garden/adding-modules.md)
-  * [Adding Services](./using-garden/adding-services.md)
-  * [Running Tests](./using-garden/running-tests.md)
-  * [Running Tasks](./using-garden/running-tasks.md)
-* [Guides](./guides/README.md)
-  * [Cloud Provider Set-up](./guides/cloud-provider-setup.md)
-  * [Configuration Files](./guides/configuration-files.md)
-  * [Container Modules](./guides/container-modules.md)
-  * [Development Workflows](./guides/development-workflows.md)
-  * [Helm Charts](./guides/using-helm-charts.md)
-  * [Hot Reload](./guides/hot-reload.md)
-  * [In-Cluster Building](./guides/in-cluster-building.md)
-  * [Local Kubernetes](./guides/local-kubernetes.md)
-  * [Remote Kubernetes](./guides/remote-kubernetes.md)
-  * [Remote Sources](./guides/using-remote-sources.md)
-  * [Terraform](./guides/terraform.md)
-  * [Variables and templating](./guides/variables-and-templating.md)
-  * [cert-manager Integration](./guides/cert-manager-integration.md)
-* [Example Projects](./examples/README.md)
-  * [Demo Project](./examples/demo-project.md)
-  * [TLS Project](./examples/tls-project.md)
-  * [Using Garden in CI](./examples/using-garden-in-ci.md)
-* [Providers](./providers/README.md)
-  * [`conftest-container`](./providers/conftest-container.md)
-  * [`conftest-kubernetes`](./providers/conftest-kubernetes.md)
-  * [`conftest`](./providers/conftest.md)
-  * [`hadolint`](./providers/hadolint.md)
-  * [`kubernetes`](./providers/kubernetes.md)
-  * [`local-kubernetes`](./providers/local-kubernetes.md)
-  * [`maven-container`](./providers/maven-container.md)
-  * [`openfaas`](./providers/openfaas.md)
-  * [`terraform`](./providers/terraform.md)
-* [Module Types](./module-types/README.md)
-  * [`conftest`](./module-types/conftest.md)
-  * [`container`](./module-types/container.md)
-  * [`exec`](./module-types/exec.md)
-  * [`hadolint`](./module-types/hadolint.md)
-  * [`helm`](./module-types/helm.md)
-  * [`kubernetes`](./module-types/kubernetes.md)
-  * [`maven-container`](./module-types/maven-container.md)
-  * [`openfaas`](./module-types/openfaas.md)
-  * [`persistentvolumeclaim`](./module-types/persistentvolumeclaim.md)
-  * [`terraform`](./module-types/terraform.md)
-* [Reference](./reference/README.md)
-  * [Glossary](./reference/glossary.md)
-  * [Commands Reference](./reference/commands.md)
-  * [Config Files Reference](./reference/config.md)
-  * [Template Strings Reference](./reference/template-strings.md)
-* [Troubleshooting](./troubleshooting.md)
-* [Telemetry](./telemetry.md)
+## 🌳 Basics
+
+* [Installation](./basics/installation.md)
+* [Quick Start](./basics/quick-start.md)
+* [Stack Graph](./basics/stack-graph.md)
+
+## 🌻 Using Garden
+
+* [Creating a Project](./using-garden/creating-a-project.md)
+* [Adding Modules](./using-garden/adding-modules.md)
+* [Adding Services](./using-garden/adding-services.md)
+* [Running Tests](./using-garden/running-tests.md)
+* [Running Tasks](./using-garden/running-tasks.md)
+
+## 💐 Guides
+
+* [Cloud Provider Set-up](./guides/cloud-provider-setup.md)
+* [Configuration Files](./guides/configuration-files.md)
+* [Container Modules](./guides/container-modules.md)
+* [Development Workflows](./guides/development-workflows.md)
+* [Helm Charts](./guides/using-helm-charts.md)
+* [Hot Reload](./guides/hot-reload.md)
+* [In-Cluster Building](./guides/in-cluster-building.md)
+* [Local Kubernetes](./guides/local-kubernetes.md)
+* [Remote Kubernetes](./guides/remote-kubernetes.md)
+* [Terraform](./guides/terraform.md)
+* [Variables and templating](./guides/variables-and-templating.md)
+* [Advanced](./guides/advanced/README.md)
+  * [Remote Sources](./guides/advanced/using-remote-sources.md)
+  * [cert-manager Integration](./guides/advanced/cert-manager-integration.md)
+
+## 🌿 Example Projects
+
+* [Demo Project](./examples/demo-project.md)
+* [TLS Project](./examples/tls-project.md)
+* [Using Garden in CI](./examples/using-garden-in-ci.md)
+
+## 🌺 Reference
+
+* [Providers](./reference/providers/README.md)
+  * [`conftest-container`](./reference/providers/conftest-container.md)
+  * [`conftest-kubernetes`](./reference/providers/conftest-kubernetes.md)
+  * [`conftest`](./reference/providers/conftest.md)
+  * [`hadolint`](./reference/providers/hadolint.md)
+  * [`kubernetes`](./reference/providers/kubernetes.md)
+  * [`local-kubernetes`](./reference/providers/local-kubernetes.md)
+  * [`maven-container`](./reference/providers/maven-container.md)
+  * [`openfaas`](./reference/providers/openfaas.md)
+  * [`terraform`](./reference/providers/terraform.md)
+* [Module Types](./reference/module-types/README.md)
+  * [`conftest`](./reference/module-types/conftest.md)
+  * [`container`](./reference/module-types/container.md)
+  * [`exec`](./reference/module-types/exec.md)
+  * [`hadolint`](./reference/module-types/hadolint.md)
+  * [`helm`](./reference/module-types/helm.md)
+  * [`kubernetes`](./reference/module-types/kubernetes.md)
+  * [`maven-container`](./reference/module-types/maven-container.md)
+  * [`openfaas`](./reference/module-types/openfaas.md)
+  * [`persistentvolumeclaim`](./reference/module-types/persistentvolumeclaim.md)
+  * [`terraform`](./reference/module-types/terraform.md)
+* [Commands](./reference/commands.md)
+* [Config Files](./reference/config.md)
+* [Template Strings](./reference/template-strings.md)
+* [Glossary](./reference/glossary.md)
+
+## ☘️ Misc
+
+* [Troubleshooting](./misc/troubleshooting.md)
+* [Telemetry](./misc/telemetry.md)

docs/basics/README.md

@@ -0,0 +1,10 @@
+---
+order: 1
+title: Basics
+---
+
+# Basics
+
+* [Installation](./installation.md)
+* [Quick Start](./quick-start.md)
+* [Stack Graph](./stack-graph.md)

docs/installation.md → docs/basics/installation.md

@@ -12,7 +12,7 @@ Please follow the guide for your operating system:
 * [Windows](#windows)
 * [Linux](#linux)
 
-If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](./guides/local-kubernetes.md)
+If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](../guides/local-kubernetes.md)
 for installation and usage information.
 
 If you want to install Garden from source, see the instructions in our [contributor guide](/~https://github.com/garden-io/garden/tree/master/CONTRIBUTING.md).
@@ -77,14 +77,14 @@ To install Docker, Kubernetes and kubectl, we recommend Docker for Mac.
 
 Please refer to their [installation guide](https://docs.docker.com/engine/installation/) for how to download and install it (which is a pretty simple process).
 
-If you'd like to use a local Kubernetes cluster, please refer to the [Local Kubernetes guide](./guides/local-kubernetes.md)
-for further information. For remote clusters, take a look at the [Remote Kubernetes guide](./guides/remote-kubernetes.md).
+If you'd like to use a local Kubernetes cluster, please refer to the [Local Kubernetes guide](../guides/local-kubernetes.md)
+for further information. For remote clusters, take a look at the [Remote Kubernetes guide](../guides/remote-kubernetes.md).
 
 ## Windows
 
 You can run Garden on Windows 10 Home, Pro or Enterprise editions.
 
-_Note: The Home edition doesn't support virtualization, but you can still use Garden if you're working with [remote Kubernetes](./guides/remote-kubernetes.md) and [in-cluster building](./guides/in-cluster-building.md)._
+_Note: The Home edition doesn't support virtualization, but you can still use Garden if you're working with [remote Kubernetes](../guides/remote-kubernetes.md) and [in-cluster building](../guides/in-cluster-building.md)._
 
 To install the Garden CLI and its dependencies, please use our installation script. To run the script, open PowerShell as an administrator and run:
 
@@ -137,7 +137,7 @@ To install Docker, please follow the instructions in the [official documentation
 
 ### Step 4 (optional): Local Kubernetes
 
-If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](./guides/local-kubernetes.md)
+If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](../guides/local-kubernetes.md)
 for installation and usage information.
 
 ## Using Garden with proxies

docs/quick-start.md → docs/basics/quick-start.md

@@ -9,7 +9,7 @@ This guide will walk you through setting up the Garden framework. It assumes you
 
 ## Using the CLI
 
-With the CLI installed, we can now try out a few commands using the [Demo Project](./examples/demo-project.md) from our [example projects](./examples/README.md). The example project consists of a couple of basic modules, each defining one service.
+With the CLI installed, we can now try out a few commands using the [Demo Project](../examples/demo-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of basic modules, each defining one service.
 
 _Note: Check whether Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._
 
@@ -75,8 +75,8 @@ garden dev
 
 Go ahead, leave it running and change one of the files in the project, then watch it re-build.
 
-That's it for now. Check out our [Using Garden](./guides/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more.
+That's it for now. Check out our [Using Garden](../guides/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more.
 
 ## Next steps
 
-To see how a Garden project is configured from scratch check, out the [Demo Project](./examples/demo-project.md) guide for a more in-depth presentation.
+To see how a Garden project is configured from scratch check, out the [Demo Project](../examples/demo-project.md) guide for a more in-depth presentation.

docs/stack-graph.md → docs/basics/stack-graph.md

@@ -71,4 +71,4 @@ Note here the first four fields, which are common across all module types—`kin
 Also notice that the `container` module explicitly declares a service, whereas the `helm` module does not. This is dictated by the module
 type. Containers often only need to be built (e.g. base images for other containers), or may contain multiple services. A Helm chart, however, is generally a single deployable so the provider makes the service implicit when configuring it.
 
-For more details on how to configure your project, take a look at the [configuration guide](./guides/configuration-files.md).
+For more details on how to configure your project, take a look at the [configuration guide](../guides/configuration-files.md).

docs/examples/demo-project.md

@@ -13,7 +13,7 @@ In what follows you'll learn how to:
 
 ## Before you get started
 
-This tutorial assumes that you already have a running [installation of Garden](../installation.md).
+This tutorial assumes that you already have a running [installation of Garden](../basics/installation.md).
 
 ## Clone the example repo
 
@@ -76,7 +76,7 @@ Above, we've specified the name of our project and configured it to use the `loc
 
 ## Module configuration
 
-Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../stack-graph.md#structure-and-terminology).
+Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure-and-terminology).
 
 We'll start with the module for the `frontend`:
 

docs/guides/README.md

@@ -41,10 +41,6 @@ Instructions for creating and configuring Kubernetes clusters with GKE (Google),
 
 The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.
 
-## [Using Remote Sources](./using-remote-sources.md)
-
-Instructions for how to import code from remote repositories into a Garden project.
-
 ## [Hot Reload](./hot-reload.md)
 
 This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers.

docs/guides/advanced/README.md

@@ -0,0 +1,9 @@
+---
+order: 10000
+title: Advanced
+---
+
+# Advanced
+
+* [cert-manager integration](./cert-manager-integration.md)
+* [Using Remote Sources](./using-remote-sources.md)

docs/guides/cert-manager-integration.md → docs/guides/advanced/cert-manager-integration.md

@@ -2,7 +2,7 @@
 
 When starting a new Kubernetes project or when maintaining your existing ones, dealing with the creation and renewal of TLS certificates can easily become a headache. A popular tool to help automate certficate generation and renewal is [cert-manager](/~https://github.com/jetstack/cert-manager).
 
-The [kubernetes](./remote-kubernetes.md) and [local-kubernetes](./local-kubernetes.md) providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults.
+The [kubernetes](../remote-kubernetes.md) and [local-kubernetes](../local-kubernetes.md) providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults.
 We don't aim to support all the features of cert-manager, but rather accommodate the most common use case, while still allowing full control of the underlying setup when needed.
 
 ## Requirements
@@ -57,7 +57,7 @@ A valid email address is also required for Let's Encrypt certificate requests.
 ### Issuing your first certificate
 
 cert-manager is a powerful tool with a lot of different possible configurations. While integrating it with Garden we decided to start with an opinionated setup which should get you up to speed quickly, without thinking too much about configuration.
-If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the [`tlsCertificates[].managedBy` config field](../providers/kubernetes.md#providerstlscertificatesmanagedby).
+If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the [`tlsCertificates[].managedBy` config field](../../reference/providers/kubernetes.md#providerstlscertificatesmanagedby).
 
 #### Example
 

docs/guides/configuration-files.md

@@ -1,7 +1,7 @@
 # Configuration Files
 
 Garden is configured via `garden.yml` configuration files, which Garden collects and compiles into a
-[Stack Graph](../stack-graph.md) of your project.
+[Stack Graph](../basics/stack-graph.md) of your project.
 
 The [project-wide](#project-configuration) `garden.yml` file should be located in the top-level directory of the
 project's Git repository.