POC / Get started onboarding revamp

docs/_snippets/_users-and-roles-common.md

@@ -42,64 +42,73 @@ Create these tables and users to be used in the examples.
 
 #### Creating a sample database, table, and rows {#creating-a-sample-database-table-and-rows}
 
-1. Create a test database
+<VerticalStepper headerLevel="h5">
 
-   ```sql
-   CREATE DATABASE db1;
-   ```
+##### Create a test database {#create-a-test-database}
 
-2. Create a table
+```sql
+CREATE DATABASE db1;
+```
 
-   ```sql
-   CREATE TABLE db1.table1 (
-       id UInt64,
-       column1 String,
-       column2 String
-   )
-   ENGINE MergeTree
-   ORDER BY id;
-   ```
+##### Create a table {#create-a-table}
 
-3. Populate the table with sample rows
+```sql
+CREATE TABLE db1.table1 (
+   id UInt64,
+   column1 String,
+   column2 String
+)
+ENGINE MergeTree
+ORDER BY id;
+```
 
-   ```sql
-   INSERT INTO db1.table1
-       (id, column1, column2)
-   VALUES
-       (1, 'A', 'abc'),
-       (2, 'A', 'def'),
-       (3, 'B', 'abc'),
-       (4, 'B', 'def');
-   ```
+##### Populate the table with sample rows {#populate}
 
-4. Verify the table:
+```sql
+INSERT INTO db1.table1
+   (id, column1, column2)
+VALUES
+   (1, 'A', 'abc'),
+   (2, 'A', 'def'),
+   (3, 'B', 'abc'),
+   (4, 'B', 'def');
+```
 
-   ```sql
-   SELECT *
-   FROM db1.table1
-   ```
+##### Verify the table {#verify}
 
-   ```response
-   Query id: 475015cc-6f51-4b20-bda2-3c9c41404e49
+```sql title="Query"
+SELECT *
+FROM db1.table1
+```
 
-   ┌─id─┬─column1─┬─column2─┐
-   │  1 │ A       │ abc     │
-   │  2 │ A       │ def     │
-   │  3 │ B       │ abc     │
-   │  4 │ B       │ def     │
-   └────┴─────────┴─────────┘
-   ```
+```response title="Response"
+Query id: 475015cc-6f51-4b20-bda2-3c9c41404e49
 
-5. Create a regular user that will be used to demonstrate restrict access to certain columns:
+┌─id─┬─column1─┬─column2─┐
+│  1 │ A       │ abc     │
+│  2 │ A       │ def     │
+│  3 │ B       │ abc     │
+│  4 │ B       │ def     │
+└────┴─────────┴─────────┘
+```
 
-   ```sql
-   CREATE USER column_user IDENTIFIED BY 'password';
-   ```
+##### Create `column_user` {#create-a-user-with-restricted-access-to-columns}
 
-6. Create a regular user that will be used to demonstrate restricting access to rows with certain values:
-   ```sql
-   CREATE USER row_user IDENTIFIED BY 'password';
-   ```
+Create a regular user that will be used to demonstrate restrict access to certain columns:
+
+```sql
+CREATE USER column_user IDENTIFIED BY 'password';
+```
+
+##### Create `row_user` {#create-a-user-with-restricted-access-to-rows-with-certain-values}
+
+Create a regular user that will be used to demonstrate restricting access to rows with certain values:
+
+```sql
+CREATE USER row_user IDENTIFIED BY 'password';
+```
+
+</VerticalStepper>
 
 #### Creating roles {#creating-roles}
 

docs/best-practices/_snippets/_table_of_contents.md

@@ -0,0 +1,12 @@
+| Page                                                                                 | Description                                                                                             |
+|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| [Choosing a Primary Key](/best-practices/choosing-a-primary-key)                     | How to select primary keys that maximize query performance and minimize storage overhead.               |
+| [Select Data Types](/best-practices/select-data-types)                               | Choose optimal data types to reduce memory usage, improve compression, and accelerate queries.          |
+| [Use Materialized Views](/best-practices/use-materialized-views)                     | Leverage materialized views to pre-aggregate data and dramatically speed up analytical queries.         |
+| [Minimize and Optimize JOINs](/best-practices/minimize-optimize-joins)               | Best practices for using ClickHouse's `JOIN` capabilities efficiently.                                  |
+| [Choosing a Partitioning Key](/best-practices/choosing-a-partitioning-key)           | Select partitioning strategies that enable efficient data pruning and faster query execution.           |
+| [Selecting an Insert Strategy](/best-practices/selecting-an-insert-strategy)         | Optimize data ingestion throughput and reduce resource consumption with proper insert patterns.         |
+| [Data Skipping Indices](/best-practices/use-data-skipping-indices-where-appropriate) | Apply secondary indices strategically to skip irrelevant data blocks and accelerate filtered queries.   |
+| [Avoid Mutations](/best-practices/avoid-mutations)                                   | Design schemas and workflows that eliminate costly `UPDATE`/`DELETE` operations for better performance. |
+| [Avoid OPTIMIZE FINAL](/best-practices/avoid-optimize-final)                         | Prevent performance bottlenecks by understanding when `OPTIMIZE FINAL` hurts more than it helps.        |
+| [Use JSON where appropriate](/best-practices/use-json-where-appropriate)             | Balance flexibility and performance when working with semi-structured JSON data in ClickHouse.          |

docs/best-practices/index.md

@@ -6,19 +6,10 @@ hide_title: true
 description: 'Landing page for Best Practices section in ClickHouse'
 ---
 
+import TableOfContents from '@site/docs/best-practices/_snippets/_table_of_contents.md';
+
 # Best Practices in ClickHouse {#best-practices-in-clickhouse}
 
 This section provides the best practices you will want to follow to get the most out of ClickHouse.
 
-| Page                                                                 | Description                                                              |
-|----------------------------------------------------------------------|--------------------------------------------------------------------------|
-| [Choosing a Primary Key](/best-practices/choosing-a-primary-key)     | Guidance on selecting an effective Primary Key in ClickHouse.            |
-| [Select Data Types](/best-practices/select-data-types)               | Recommendations for choosing appropriate data types.                     |
-| [Use Materialized Views](/best-practices/use-materialized-views)     | When and how to benefit from materialized views.                         |
-| [Minimize and Optimize JOINs](/best-practices/minimize-optimize-joins)| Best practices for minimizing and optimizing JOIN operations.            |
-| [Choosing a Partitioning Key](/best-practices/choosing-a-partitioning-key) | How to choose and apply partitioning keys effectively.              |
-| [Selecting an Insert Strategy](/best-practices/selecting-an-insert-strategy) | Strategies for efficient data insertion in ClickHouse.             |
-| [Data Skipping Indices](/best-practices/use-data-skipping-indices-where-appropriate) | When to apply data skipping indices for performance gains.    |
-| [Avoid Mutations](/best-practices/avoid-mutations)                   | Reasons to avoid mutations and how to design without them.               |
-| [Avoid OPTIMIZE FINAL](/best-practices/avoid-optimize-final)         | Why `OPTIMIZE FINAL` can be costly and how to work around it.           |
-| [Use JSON where appropriate](/best-practices/use-json-where-appropriate) | Considerations for using JSON columns in ClickHouse.               |
+<TableOfContents/>

docs/cloud/_snippets/_security_table_of_contents.md

@@ -0,0 +1,8 @@
+| Page                                                          | Description                                                                                                                        |
+|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
+| [Shared Responsibility Model](/cloud/security/shared-responsibility-model) | Understand how security responsibilities are divided between ClickHouse Cloud and your organization for different service types.   |
+| [Cloud Access Management](/cloud/security/cloud-access-management)   | Manage user access with authentication, single sign-on (SSO), role-based permissions, and team invitations.                        |
+| [Connectivity](/cloud/security/connectivity)                      | Configure secure network access including IP allow-lists, private networking, S3 data access, and Cloud IP address management.     |
+| [Enhanced Encryption](/cloud/security/cmek)                                | Learn about default AES 256 encryption and how to enable Transparent Data Encryption (TDE) for additional data protection at rest. |
+| [Audit Logging](/cloud/security/audit-logging)                             | Set up and use audit logging to track and monitor activities in your ClickHouse Cloud environment.                                 |
+| [Privacy and Compliance](/cloud/security/privacy-compliance-overview)      | Review security certifications, compliance standards, and learn how to manage your personal information and data rights.           |

docs/cloud/manage/api/api-overview.md → docs/cloud/api/api-overview.md

@@ -15,7 +15,7 @@ organizations and services on ClickHouse Cloud. Using our Cloud API, you can
 create and manage services, provision API keys, add or remove members in your 
 organization, and more.
 
-[Learn how to create your first API key and start using the ClickHouse Cloud API.](/cloud/manage/openapi.md)
+[Learn how to create your first API key and start using the ClickHouse Cloud API.](/cloud/manage/openapi)
 
 ## Swagger (OpenAPI) Endpoint and UI {#swagger-openapi-endpoint-and-ui}
 
@@ -56,7 +56,8 @@ If your organization has been migrated to one of the [new pricing plans](https:/
 You will now also be able to specify the `num_replicas` field as a property of the service resource.
 :::
 
-## Terraform and OpenAPI New Pricing: Replica Settings Explained
+## Terraform and OpenAPI New Pricing: Replica Settings Explained {#terraform-and-openapi-new-pricing---replica-settings-explained}
+
 The number of replicas each service will be created with defaults to 3 for the Scale and Enterprise tiers, while it defaults to 1 for the Basic tier.
 For the Scale and the Enterprise tiers it is possible to adjust it by passing a `numReplicas` field in the service creation request. 
 The value of the `numReplicas` field must be between 2 and 20 for the first service in a warehouse. Services that are created in an existing warehouse can have a number of replicas as low as 1.

docs/cloud/manage/openapi.md → docs/cloud/api/openapi.md

@@ -17,7 +17,7 @@ import Image from '@theme/IdealImage';
 ClickHouse Cloud provides an API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services.
 
 :::note
-This document covers the ClickHouse Cloud API. For database API endpoints, please see [Cloud Endpoints API](/cloud/get-started/query-endpoints.md)
+This document covers the ClickHouse Cloud API. For database API endpoints, please see [Cloud Endpoints API](/cloud/get-started/query-endpoints)
 :::
 
 1. You can use the **API Keys** tab on the left menu to create and manage your API keys.

docs/cloud/manage/cloud-tiers.md → docs/cloud/features/01_cloud_tiers.md

@@ -164,17 +164,17 @@ This page discusses which tiers are right for your specific use case.
 
 :::note
 Services in the basic tier are meant to be fixed in size and do not allow scaling, both automatic and manual. 
-Users can upgrade to the Scale or Enterprise tier to scale their services.
+You can upgrade to the Scale or Enterprise tier to scale their services.
 :::
 
 ## Scale {#scale}
 
 Designed for workloads requiring enhanced SLAs (2+ replica deployments), scalability, and advanced security.
 
 - Offers support for features such as: 
-  - [Private networking support](../security/private-link-overview.md).
+  - [Private networking support](/cloud/security/private-link-overview).
   - [Compute-compute separation](../reference/warehouses#what-is-compute-compute-separation).
-  - [Flexible scaling](../manage/scaling.md) options (scale up/down, in/out).
+  - [Flexible scaling](/manage/scaling) options (scale up/down, in/out).
 
 ## Enterprise {#enterprise}
 
@@ -186,8 +186,8 @@ Caters to large-scale, mission critical deployments that have stringent security
 - Supports enterprise-grade security:
   - Single Sign On (SSO)
   - Enhanced Encryption: For AWS and GCP services. Services are encrypted by our key by default and can be rotated to their key to enable Customer Managed Encryption Keys (CMEK).
-- Allows Scheduled upgrades: Users can select the day of the week/time window for upgrades, both database and cloud releases.  
-- Offers [HIPAA](../security/compliance-overview.md/#hipaa-since-2024) Compliance.
+- Allows Scheduled upgrades: you can select the day of the week/time window for upgrades, both database and cloud releases.  
+- Offers [HIPAA](/cloud/security/compliance-overview#hipaa-since-2024) Compliance.
 - Exports Backups to the user's account.
 
 :::note 

docs/cloud/features/02_cloud_console_features/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Cloud console",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/features/03_infrastructure_and_deploy/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Infrastructure and deploy",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/reference/byoc.md → docs/cloud/features/03_infrastructure_and_deploy/byoc.md

@@ -128,7 +128,7 @@ Contact ClickHouse Support to enable Private Load Balancer.
 2. Select Peering Connections.
 3. Click Create Peering Connection
 4. Set the VPC Requester to the ClickHouse VPC ID.
-5. Set the VPC Acceptor to the target VPC ID. (Select another account if applicable)
+5. Set the VPC Accepter to the target VPC ID. (Select another account if applicable)
 6. Click Create Peering Connection.
 
 <br />

docs/cloud/features/04_monitoring/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Monitoring",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/manage/monitoring/advanced_dashboard.md → docs/cloud/features/04_monitoring/advanced_dashboard.md

@@ -110,7 +110,7 @@ interface can help detect issues.
 | Network receive bytes/sec      | Tracks the current speed of outbound network traffic        |
 | Concurrent network connections | Tracks the number of current concurrent network connections |
 
-## Identifying issues with the Advanced dashboard {#identifying-issues-with-the-advanced-dashboard}
+## Identifying issues using the advanced dashboard {#identifying-issues-with-the-advanced-dashboard}
 
 Having this real-time view of the health of your ClickHouse service greatly helps
 mitigate issues before they impact your business or help solve them. Below are a