Docs: restructure for Mintlify sync workflow

AGENTS.md

@@ -50,7 +50,7 @@ go test ./internal/controller/keeper/ -v --ginkgo.v --ginkgo.focus="spec name pa
 make generate               # DeepCopy methods (zz_generated.deepcopy.go)
 make manifests              # CRDs, RBAC roles, webhooks → config/crd/bases/
 make generate-helmchart-ci  # Generate Helm chart templates and reset manually maintained files (dist/chart/templates/)
-make docs-generate-api-ref  # Generate API reference docs (docs/api-reference.md)
+make docs-generate-api-ref  # Generate API reference docs (docs/reference/api-reference.mdx)
 ```
 
 ### Helm Chart

Makefile

@@ -602,7 +602,7 @@ docs-generate-api-ref: crd-ref-docs ## Generate API reference documentation from
 		--config=docs/templates/.crd-ref-docs.yaml \
 		--templates-dir=docs/templates \
 		--renderer=markdown \
-		--output-path=docs/api_reference.md \
+		--output-path=docs/reference/api-reference.mdx \
 		--max-depth=10
 
 .PHONY: docs-lint-vale

docs/README.md

@@ -15,7 +15,7 @@ Choose your preferred installation method:
 
 ## Reference
 
-- **[API Reference](./api_reference.md)** - Complete API documentation for custom resources
+- **[API Reference](./reference/api-reference.mdx)** - Complete API documentation for custom resources
 - [ClickHouse Documentation](https://clickhouse.com/docs) - Official ClickHouse documentation
 
 ## Development

docs/configuration.md → docs/guides/configuration.mdx

@@ -1,22 +1,10 @@
-# Configuration Guide
+# ClickHouse Operator configuration guide
 
 This guide covers how to configure ClickHouse and Keeper clusters using the operator.
 
-## Table of Contents
+## ClickHouseCluster configuration {#clickhousecluster-configuration}
 
-- [ClickHouseCluster Configuration](#clickhousecluster-configuration)
-- [KeeperCluster Configuration](#keepercluster-configuration)
-- [Storage Configuration](#storage-configuration)
-- [Pod Configuration](#pod-configuration)
-- [Container Configuration](#container-configuration)
-- [TLS/SSL Configuration](#tlsssl-configuration)
-- [ClickHouse Settings](#clickhouse-settings)
-- [Custom Configuration](#custom-configuration)
-- [Example Configuration](#configuration-example)
-
-## ClickHouseCluster Configuration
-
-### Basic Configuration
+### Basic configuration {#basic-configuration}
 
 ```yaml
 apiVersion: clickhouse.com/v1alpha1
@@ -29,14 +17,12 @@ spec:
   keeperClusterRef:
     name: my-keeper     # Reference to KeeperCluster
   dataVolumeClaimSpec:
-    accessModes:
-      - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
 ```
 
-### Replicas and Shards
+### Replicas and shards {#replicas-and-shards}
 
 - **Replicas**: Number of ClickHouse instances per shard (for high availability)
 - **Shards**: Number of horizontal partitions (for scaling)
@@ -49,7 +35,7 @@ spec:
 
 A cluster with `replicas: 3` and `shards: 2` will create 6 ClickHouse pods total.
 
-### Keeper Integration
+### Keeper integration {#keeper-integration}
 
 Every ClickHouse cluster must reference a KeeperCluster for coordination:
 
@@ -62,7 +48,7 @@ spec:
 
 When `keeperClusterRef.namespace` is set, the operator must watch both namespaces. If `WATCH_NAMESPACE` is configured, include the ClickHouse and Keeper namespaces in that list.
 
-## KeeperCluster Configuration
+## KeeperCluster configuration {#keepercluster-configuration}
 
 ```yaml
 apiVersion: clickhouse.com/v1alpha1
@@ -72,14 +58,12 @@ metadata:
 spec:
   replicas: 3  # Must be odd: 1, 3, 5, 7, 9, 11, 13, or 15
   dataVolumeClaimSpec:
-    accessModes:
-      - ReadWriteOnce
     resources:
       requests:
         storage: 5Gi
 ```
 
-## Storage Configuration
+## Storage configuration {#storage-configuration}
 
 Configure persistent storage:
 
@@ -92,11 +76,13 @@ spec:
         storage: 100Gi
 ```
 
-**NOTE:** Operator can modify existing PVC only if the underlying storage class supports volume expansion.
+<Note>
+Operator can modify existing PVC only if the underlying storage class supports volume expansion.
+</Note>
 
-## Pod Configuration
+## Pod configuration {#pod-configuration}
 
-### Automatic Topology Spread and Affinity
+### Automatic topology spread and affinity {#automatic-topology-spread-and-affinity}
 
 Distribute pods across availability zones:
 
@@ -107,9 +93,11 @@ spec:
     nodeHostnameKey: kubernetes.io/hostname
 ```
 
-**NOTE**: Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints.
+<Note>
+Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints.
+</Note>
 
-### Manual configuration
+### Manual configuration {#manual-configuration}
 
 Arbitrary pod affinity/anti-affinity rules and topology spread constraints can be specified.
 
@@ -122,11 +110,11 @@ spec:
       <your-topology-spread-constraints-here>
 ```
 
-### See [API Reference](./api_reference.md#PodTemplateSpec) for all supported Pod template options.
+### See [API Reference](/products/kubernetes-operator/reference/api-reference#podtemplatespec) for all supported Pod template options.
 
-## Container Configuration
+## Container configuration {#container-configuration}
 
-### Custom Image
+### Custom image {#custom-image}
 
 Use a specific ClickHouse image:
 
@@ -139,7 +127,7 @@ spec:
     imagePullPolicy: IfNotPresent
 ```
 
-### Container Resources
+### Container resources {#container-resources}
 
 Configure CPU and memory for ClickHouse containers:
 
@@ -156,8 +144,7 @@ spec:
         memory: "1Gi"
 ```
 
-### Environment Variables
-
+### Environment variables {#environment-variables}
 
 Add custom environment variables:
 
@@ -169,7 +156,7 @@ spec:
       value: "1"
 ```
 
-### Volume Mounts
+### Volume mounts {#volume-mounts}
 
 Add additional volume mounts:
 
@@ -182,14 +169,16 @@ spec:
       subPath: custom.xml
 ```
 
-**NOTE:** It is allowed to specify multiple volume mounts to the same `mountPath`.
+<Note>
+It is allowed to specify multiple volume mounts to the same `mountPath`.
 Operator will create projected volume with all specified mounts.
+</Note>
 
-### See [API Reference](./api_reference.md#ContainerTemplateSpec) for all supported Container template options.
+### See [API Reference](/products/kubernetes-operator/reference/api-reference#containertemplatespec) for all supported Container template options.
 
-## TLS/SSL Configuration
+## TLS/SSL configuration {#tls-ssl-configuration}
 
-### Configure secure endpoints
+### Configure secure endpoints {#configure-secure-endpoints}
 
 Pass a reference to a Kubernetes Secret containing TLS certificates to enable secure endpoints
 
@@ -203,20 +192,22 @@ spec:
         name: <certificate-secret-name>
 ```
 
-### SSL Certificate Secret format
+### SSL certificate secret format {#ssl-certificate-secret-format}
 
 It is expected that the Secret contains the following keys:
 - `tls.crt` - PEM encoded server certificate
 - `tls.key` - PEM encoded private key
 - `ca.crt` - PEM encoded CA certificate chain
 
-**NOTE:** This format is compatible with cert-manager generated certificates.
+<Note>
+This format is compatible with cert-manager generated certificates.
+</Note>
 
-### ClickHouse-Keeper communication over TLS
+### ClickHouse-Keeper communication over TLS {#clickhouse-keeper-communication-over-tls}
 
 If KeeperCluster has TLS enabled, ClickHouseCluster would use secure connection to Keeper nodes automatically.
 
-ClickHouseCluster should be able to verify Keeper nodes certificates. 
+ClickHouseCluster should be able to verify Keeper nodes certificates.
 If ClickHouseCluster has TLS enabled, is uses `ca.crt` bundle for verification. Otherwise, default CA bundle is used.
 
 User may provide a custom CA bundle reference:
@@ -230,9 +221,9 @@ spec:
             key: <ca-certificate-key>
 ```
 
-## ClickHouse Settings
+## ClickHouse settings {#clickhouse-settings}
 
-### Default User Password
+### Default user password {#default-user-password}
 
 Set the default user password:
 
@@ -246,15 +237,17 @@ spec:
         key: <password>
 ```
 
-**NOTE** It is not recommended to use ConfigMap to store plain text passwords.
+<Note>
+It isn't recommended to use ConfigMap to store plain text passwords.
+</Note>
 
 Create the secret:
 
 ```bash
 kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'
 ```
 
-#### Using ConfigMap for User Passwords
+#### Using ConfigMap for user passwords {#using-configmap-for-user-passwords}
 
 You can also use ConfigMap for non-sensitive default passwords:
 
@@ -268,7 +261,7 @@ spec:
         key: default_password
 ```
 
-### Custom Users in configuration
+### Custom users in configuration {#custom-users-in-configuration}
 
 Configure additional users in configuration files.
 
@@ -320,7 +313,7 @@ spec:
         readOnly: true
 ```
 
-### Database Sync
+### Database sync {#database-sync}
 
 Enable automatic database synchronization for new replicas:
 
@@ -332,9 +325,9 @@ spec:
 
 When enabled, the operator synchronizes Replicated and integration tables to new replicas.
 
-## Custom Configuration
+## Custom configuration {#custom-configuration}
 
-### Embedded Extra Configuration
+### Embedded extra configuration {#embedded-extra-configuration}
 
 Instead of mounting custom configuration files, you can directly specify additional ClickHouse configuration options.
 
@@ -348,10 +341,10 @@ spec:
 ```
 
 #### Useful links:
-* [YAML configuration examples](https://clickhouse.com/docs/operations/configuration-files#example-1)
-* [All server settings](https://clickhouse.com/docs/operations/server-configuration-parameters/settings)
+* [YAML configuration examples](/concepts/features/configuration/server-config/configuration-files#example-1)
+* [All server settings](/reference/settings/server-settings/settings)
 
-### Embedded Extra Users Configuration
+### Embedded extra users configuration {#embedded-extra-users-configuration}
 
 You can also specify additional ClickHouse users configuration using `extraUsersConfig`. This is useful for defining users, profiles, quotas, and grants directly in the cluster specification.
 
@@ -377,11 +370,13 @@ spec:
             errors: 100
 ```
 
-**Note**: The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there.
+<Note>
+The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there.
+</Note>
 
-#### See [documentation](https://clickhouse.com/docs/operations/settings/settings-users) for all supported ClickHouse users configuration options.
+#### See [documentation](/concepts/features/configuration/settings/settings-users) for all supported ClickHouse users configuration options.
 
-### Configuration Example
+### Configuration example {#configuration-example}
 
 Complete configuration example:
 
@@ -394,8 +389,6 @@ spec:
   replicas: 3
   dataVolumeClaimSpec:
     storageClassName: <storage-class-name>
-    accessModes:
-      - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
@@ -433,8 +426,6 @@ spec:
   replicas: 2
   dataVolumeClaimSpec:
     storageClassName: <storage-class-name>
-    accessModes:
-      - ReadWriteOnce
     resources:
       requests:
         storage: 200Gi