Docs: Refactor Getting Started (#731)

Co-authored-by: Sean Park-Ross <[email protected]>

docs/_install-the-cli.mdx

@@ -4,8 +4,6 @@ import CodeBlock from "@theme/CodeBlock";
 import Version from "@site/src/components/CliVersion";
 import Admonition from "@theme/Admonition";
 
-<Version />
-
 <Tabs groupId="os-preference" className="api-tabs">
 
 <TabItem value="macOS-or-linux" label="macOS and Linux">

docs/_prereqs.mdx

@@ -0,0 +1,25 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import CodeBlock from "@theme/CodeBlock";
+import Version from "@site/src/components/CliVersion";
+import Admonition from "@theme/Admonition";
+import InstallTheCli from "@site/docs/_install-the-cli.mdx";
+
+## Prerequisites
+
+**Install the DDN CLI**
+
+<InstallTheCli />
+
+**Install [Docker](https://docs.docker.com/engine/install/)**
+
+The Docker based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the
+development experience faster and your feedback loops shorter. **You'll need Docker Compose `v2.27.1` or later.**
+
+**Validate the installation**
+
+You can verify that the DDN CLI is installed correctly by running:
+
+```sh
+ddn doctor
+```

docs/getting-started/explore/explore-your-api.mdx → docs/basics/explore/explore-your-api.mdx

@@ -35,8 +35,8 @@ The console's — Hasura's web-based GUI — explorer page offers:
 - **Enhanced Collaboration:** Foster better communication and coordination across teams with a shared, intuitive visual
   tool.
 
-You can also use the console to [interact with](/getting-started/explore/interact.mdx) and
-[monitor](/getting-started/explore/monitor.mdx) your API.
+You can also use the console to [interact with](/basics/explore/interact.mdx) and [monitor](/basics/explore/monitor.mdx)
+your API.
 
 ## Step 1. Explore your supergraph
 
@@ -194,4 +194,4 @@ activity without making changes.
 ## Next steps
 
 Now that you have the knowledge to explore your API, let's see how easy it is to
-[interact with and test your API](/getting-started/explore/interact.mdx) using the GraphiQL explorer.
+[interact with and test your API](/basics/explore/interact.mdx) using the GraphiQL explorer.

docs/getting-started/explore/index.mdx → docs/basics/explore/index.mdx

@@ -66,5 +66,5 @@ want to easily see what Hasura can do, you can start exploring a finished superg
 To explore a sample eCommerce supergraph API built on Hasura DDN
 ([source code](https://github.com/hasura/ddn-sample-app)), simply head to the
 [DDN console](https://console.hasura.io/projects). You should see an "eCommerce App" sample project under **Sample
-Projects**. Then, to get started with the console, head [here](/getting-started/explore/explore-your-api.mdx) to learn
-how to start using the explorer.
+Projects**. Then, to get started with the console, head [here](/basics/explore/explore-your-api.mdx) to learn how to
+start using the explorer.

docs/getting-started/explore/interact.mdx → docs/basics/explore/interact.mdx

@@ -34,8 +34,8 @@ With Hasura DDN, you can use our GraphiQL explorer to create and test queries di
 - **Built-in Tracing:** Instantly trace queries to identify performance bottlenecks and optimize efficiently.
 - **Streamlined Workflow:** Save time and reduce context-switching by having everything you need in a single interface.
 
-You can also use the console to [visualize](/getting-started/explore/explore-your-api.mdx) and
-[monitor](/getting-started/explore/monitor.mdx) your API.
+You can also use the console to [visualize](/basics/explore/explore-your-api.mdx) and
+[monitor](/basics/explore/monitor.mdx) your API.
 
 ## Step 1. Test your supergraph API
 
@@ -107,4 +107,4 @@ The API expects `content-type` to be present. Removing it will return an error.
 ## Next steps
 
 Now that you've tested your API, viewed traces, and explored the schema, learn how to
-[monitor your API's performance](/getting-started/explore/monitor.mdx).
+[monitor your API's performance](/basics/explore/monitor.mdx).

docs/getting-started/explore/monitor.mdx → docs/basics/explore/monitor.mdx

@@ -41,8 +41,8 @@ Aside from the information below, you can dig into our observability options [he
 
 :::
 
-You can also use the console to [visualize](/getting-started/explore/explore-your-api.mdx) and
-[interact with](/getting-started/explore/interact.mdx) your API.
+You can also use the console to [visualize](/basics/explore/explore-your-api.mdx) and
+[interact with](/basics/explore/interact.mdx) your API.
 
 From the sidenav of the console — Hasura's web-based GUI — you can access the `Insights` page.
 
@@ -56,11 +56,11 @@ You can access key performance metrics for both your project and for each build:
 
 You can also click the `Traces` tab at the top of the page and get query-by-query trace data for each request, seeing
 all the same details as when using the
-[`View Trace` button in the GraphiQL explorer](/getting-started/explore/interact.mdx#traces).
+[`View Trace` button in the GraphiQL explorer](/basics/explore/interact.mdx#traces).
 
 <Thumbnail src="/img/get-started/traces-overview.png" alt="A build's traces page" width="1000px" />
 
 ## Next steps
 
 With a complete picture of everything the console has to offer, aren't you ready to build your first supergraph?! Head
-to the [Build an API section](/getting-started/build/prerequisites/) to get started 🎉
+to the [Build an API section](/getting-started/quickstart.mdx) to get started 🎉

docs/business-logic/introduction.mdx

@@ -83,10 +83,10 @@ To get started with Hasura's lambda connectors and enjoy the benefits of:
 
 Explore the following resources:
 
-- [Using the TypeScript connector](/getting-started/build/06-add-business-logic.mdx?db=TypeScript).
-- [Using the Python connector](/getting-started/build/06-add-business-logic.mdx?db=Python).
-- [Using the Go connector](/getting-started/build/06-add-business-logic.mdx?db=Go).
+- [Using the TypeScript connector](/getting-started/quickstart.mdx).
+- [Using the Python connector](/getting-started/quickstart.mdx).
+- [Using the Go connector](/getting-started/quickstart.mdx).
 - Learn how to integrate existing REST services using the
-  [OpenAPI connector](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=OpenAPI).
+  [OpenAPI connector](/getting-started/quickstart.mdx).
 - Learn how to integrate existing GraphQL services using the
-  [GraphQL connector](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=GraphQL).
+  [GraphQL connector](/getting-started/quickstart.mdx).

docs/business-logic/typescript.mdx

@@ -322,7 +322,7 @@ GraphQL API.
 :::info More examples
 
 To see more examples, check out our getting started guide for
-[adding custom business logic](/getting-started/build/06-add-business-logic.mdx) or database-specific guides for
-[creating mutations](/getting-started/build/08-mutate-data.mdx).
+[adding custom business logic](/getting-started/quickstart.mdx) or database-specific guides for
+[creating mutations](/getting-started/quickstart.mdx).
 
 :::

docs/collaboration/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Collaboration",
+  "position": 6.5,
+  "className": "collaboration-icon",
+  "customProps": {
+    "sidebar_pathname": "collaboration"
+  }
+}

docs/getting-started/collaborate/comment.mdx → docs/collaboration/comment.mdx

@@ -43,16 +43,16 @@ You can add comments on various objects from your metadata.
 
 You can add comments to the following areas:
 
-### Explorer Tab 
+### Explorer Tab
 
 #### Supergraph Page
 
-<Thumbnail src="/img/get-started/comments_supergraph.png" alt="Hover over fields to add comments" width="800" /> 
+<Thumbnail src="/img/get-started/comments_supergraph.png" alt="Hover over fields to add comments" width="800" />
 <br />
 
 #### Subgraph Page
 
-<Thumbnail src="/img/get-started/comments_subgraph.png" alt="Hover over fields to add comments" width="500" /> 
+<Thumbnail src="/img/get-started/comments_subgraph.png" alt="Hover over fields to add comments" width="500" />
 <br />
 
 #### Models --> General
@@ -104,30 +104,30 @@ You can add comments to the following areas:
 
 <Thumbnail src="/img/get-started/comments_builds.png" alt="Comments on Permissions" width="1000" />
 
-
 ## Notifications
 
 To ensure effective collaboration, you can tag subgraph collaborators in your comments:
 
 1. Type `@` in your comment.
 2. Select the collaborator you want to notify.
 
-Tagged collaborators will receive an email with your comments and a notification on the notification hub on the console, 
+Tagged collaborators will receive an email with your comments and a notification on the notification hub on the console,
 keeping them informed of any discussions or questions.
 
-The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see all the comments
-where you are tagged in one place. The messages will be grouped based on the underlying commenting thread. You can click on a particular comment (deep linking) and go to the original thread on the console. 
-You can also delete notifications from that menu.
+The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see
+all the comments where you are tagged in one place. The messages will be grouped based on the underlying commenting
+thread. You can click on a particular comment (deep linking) and go to the original thread on the console. You can also
+delete notifications from that menu.
 
 {/* <Thumbnail src="/img/get-started/comments_notification.png" alt="Alt text" width="100" height="100" /> */}
 ![Alt text](/img/get-started/comments_notification.png)
+
 <br />
 <br />
 
 :::info Invite collaborators
 
-You can learn how to invite collaborators [here](/getting-started/collaborate/invite.mdx).
-
+You can learn how to invite collaborators [here](/collaboration/invite.mdx).
 
 :::
 

docs/getting-started/collaborate/federation.mdx → docs/collaboration/federation.mdx

@@ -29,8 +29,8 @@ In order to add subgraph collaborators, your project must be a [DDN Advanced pro
 
 Hasura DDN provides a concept of [subgraph](/project-configuration/subgraphs/#introduction) which allows you to manage
 your Hasura metadata more efficiently by allowing it to be split based on ownership. Hasura DDN allows multiple users
-and teams to [work together as collaborators](/getting-started/collaborate/invite.mdx) on subgraphs by assigning each
-user specific roles and permissions.
+and teams to [work together as collaborators](/collaboration/invite.mdx) on subgraphs by assigning each user
+specific roles and permissions.
 
 In this guide, you'll learn how to onboard multiple teams into a collaborative project using a supergraph. This approach
 allows for efficient collaboration making it easier to manage and scale your project as more teams are added.
@@ -49,8 +49,8 @@ The Fulfillment team is already using Hasura DDN and has created a supergraph pr
 [models](/supergraph-modeling/models.mdx) enabled.
 
 When the UX Team joins the project, you'll use the [CLI](/cli/installation.mdx) to create a new subgraph for them, named
-`ux` and [invite developers](/getting-started/collaborate/invite.mdx) from the team to collaborate on this subgraph via
-the console.
+`ux` and [invite developers](/collaboration/invite.mdx) from the team to collaborate on this subgraph via the
+console.
 
 The UX team will start by initializing a new local DDN project with their own new version control repository and set the
 project context to match the existing project set up by the Fulfillment team.
@@ -76,14 +76,14 @@ ddn project subgraph create <subgraph-name>
 
 ### Step 2. Invite collaborators
 
-[Follow the steps ](/getting-started/collaborate/invite.mdx#invite-collaborators) to invite subgraph collaborators. Take
+[Follow the steps ](/collaboration/invite.mdx#invite-collaborators) to invite subgraph collaborators. Take
 care to select the appropriate role — either **Admin** or **Developer** — for each subgraph team member.
 
 ## As a subgraph developer, collaborate on the new subgraph
 
 ### Step 1. Accept the invite
 
-[Reference these docs](/getting-started/collaborate/invite.mdx#accept-invite) to accept an invitation and explore the
+[Reference these docs](/collaboration/invite.mdx#accept-invite) to accept an invitation and explore the
 existing supergraph.
 
 ### Step 2. Create a new local project, supergraph and subgraph

docs/getting-started/collaborate/index.mdx → docs/collaboration/index.mdx

@@ -22,5 +22,5 @@ service.
 
 ## Next steps
 
-- [Learn how to invite others](getting-started/collaborate/invite.mdx) to a project
-- Read about the [best practices](getting-started/collaborate/best-practices.mdx) for developing as a team
+- [Learn how to invite others](/collaboration/invite.mdx) to a project
+- Read about the [best practices](/collaboration/best-practices.mdx) for developing as a team

docs/getting-started/collaborate/invite.mdx → docs/collaboration/invite.mdx

@@ -107,7 +107,7 @@ From your new project, you can explore the console by:
 
 The owner of the project most likely has a Git repository with the project's contents available on a service such as
 GitHub. To run the supergraph locally, and make contributions to the deployed supergraph,
-[pick up here](/getting-started/build/build-your-api) in our getting started docs.
+[pick up here](/getting-started/quickstart.mdx) in our getting started docs.
 
 ## Allow users to request access {#request-access}
 

docs/collaboration/overview.mdx

@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+description:
+  "Hasura DDN allows multiple users and teams to work together as collaborators on projects by assigning each user specific roles and permissions."
+keywords:
+  - hasura ddn
+  - graphql api
+hide_table_of_contents: true
+---
+
+import { OverviewTopSectionIconNoVideo } from "@site/src/components/OverviewTopSectionIconNoVideo";
+import { OverviewPlainCard } from "@site/src/components/OverviewPlainCard";
+import Icon from '@site/static/icons/features/collaborators.svg';
+
+# Collaboration
+
+<OverviewTopSectionIconNoVideo
+  icon={<Icon />}
+  links={[]}
+  intro={
+    <div>
+      <p>
+        Hasura DDN allows multiple users and teams to work together as collaborators on projects by assigning each user specific roles and permissions. 
+      </p>
+    </div>
+  }
+/>
+
+<div className="overview-gallery card-wrapper">
+
+<OverviewPlainCard
+  title="Invite Users"
+  body="You can add users to your project by providing their email address and assigning them a role."
+  link="/collaboration/invite/"
+  linkText={"Learn more"}
+/>
+
+<OverviewPlainCard
+  title="Best Practices"
+  body="Learn about best practices for collaboration in Hasura DDN."
+  link="/collaboration/best-practices/"
+  linkText={"Learn more"}
+/>
+
+<OverviewPlainCard
+  title="Comments"
+  body="You can communicate with your team by adding comments to your project on Hasura DDN."
+  link="/collaboration/comment/"
+  linkText={"Learn more"}
+/>
+
+</div>

docs/connectors/clickhouse/index.mdx

@@ -27,7 +27,7 @@ overview of the features of the ClickHouse connector and how to configure it in
 ## Getting started
 
 To get started with ClickHouse and Hasura DDN, check out
-[this guide](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=ClickHouse).
+[this guide](/getting-started/quickstart.mdx).
 
 :::info Prerequisites
 

docs/connectors/external-apis/graphql.mdx

@@ -54,7 +54,7 @@ Below, you'll find a matrix of all supported features for the GraphQL connector:
 ## Getting started
 
 To get started with the GraphQL Data Connector, you can follow the
-[guide here](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=GraphQL).
+[guide here](/getting-started/quickstart.mdx).
 
 :::info Prerequisites
 

docs/connectors/external-apis/open-api.mdx

@@ -37,7 +37,7 @@ mutate data.
 ## Getting started
 
 To get started with the OpenAPI Lambda Connector, you can follow the
-[guide here](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=OpenAPI).
+[guide here](/getting-started/quickstart.mdx).
 
 :::info Prerequisites
 

docs/connectors/mongodb/index.mdx

@@ -37,7 +37,7 @@ configuration, the connector supports introspecting the database via the Hasura
 ## Getting started
 
 To get started with MongoDB and Hasura DDN, check out
-[this guide](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=MongoDB).
+[this guide](/getting-started/quickstart.mdx).
 
 :::info Prerequisites
 

docs/connectors/postgresql/index.mdx

@@ -54,7 +54,7 @@ Our policy is to support all versions which are indicated as being supported in
 ## Getting started
 
 To get started with PostgreSQL and Hasura DDN, check out
-[this guide](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=PostgreSQL).
+[this guide](/getting-started/quickstart.mdx).
 
 :::info Prerequisites
 

docs/connectors/postgresql/local-postgres.mdx

@@ -114,15 +114,15 @@ You can now create tables, add data, etc. on the Postgres database and iterate o
 
 You can connect the Postgres database to your supergraph using the
 [Postgres data connector](connectors/postgresql/index.mdx) by following the steps in
-[this guide](/getting-started/build/03-connect-to-data/01-connect-a-source.mdx?db=PostgreSQL) and providing the database
+[this guide](/getting-started/quickstart.mdx) and providing the database
 connection string as the following:
 
 ```bash title="Connection string to connect to local supergraph"
 postgresql://user:[email protected]:5432/dev
 ```
 
 As you iterate on your database schema you can update your supergraph metadata using the steps in
-[this guide](/getting-started/build/03-connect-to-data/02-create-source-metadata.mdx).
+[this guide](/getting-started/quickstart.mdx).
 
 :::warning Connecting to your local database from the cloud
 

docs/connectors/postgresql/native-operations/custom-mutations.mdx

@@ -67,7 +67,7 @@ CLI to add it to the connector configuration. For example:
    ```
 
 4. Add a source entity as described in our
-   [add source entities](/getting-started/build/03-connect-to-data/02-create-source-metadata.mdx) guide.
+   [add source entities](/getting-started/quickstart.mdx) guide.
 
 ## List Native Operations
 

docs/connectors/postgresql/native-operations/custom-queries.mdx

@@ -51,7 +51,7 @@ to add it to the connector configuration. For example:
    ```
 
 4. Add a source entity as described in our
-   [add source entities](/getting-started/build/03-connect-to-data/02-create-source-metadata.mdx) guide.
+   [add source entities](/getting-started/quickstart.mdx) guide.
 
 ## List Native Operations
 

docs/connectors/postgresql/native-operations/vector-search.mdx

@@ -72,9 +72,8 @@ relationship from this projection to the full products table and query it flexib
 ### Hasura metadata
 
 First, you would need to track the newly-available collection from the step above as types / models in your project's
-metadata ([see instructions here](/docs/getting-started/build/03-connect-to-data/02-create-source-metadata.mdx)). Then,
-you would need to add a relationship from the generated `ProductsVectorDistance` type to the main `Products` model, like
-this:
+metadata ([see instructions here](/getting-started/quickstart.mdx)). Then, you would need to add a relationship from the
+generated `ProductsVectorDistance` type to the main `Products` model, like this:
 
 ```yaml
 kind: Relationship