Refactor documentation to use it as source for docs website

.github/workflows/docs-lint.yaml

@@ -27,8 +27,10 @@ jobs:
       - uses: actions/checkout@v6
       - uses: tcort/github-action-markdown-link-check@v1
         with:
-          config-file: ci/.markdown-link-check.json
-          file-extension: '.md'
+          file-path: |
+            README.md
+            docs/README.md
+            docs/development.md
 
   api-reference-generated:
     name: API Reference Generated

Makefile

@@ -516,7 +516,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/04_api_reference.md \
 		--max-depth=10
 
 .PHONY: docs-lint-vale
@@ -527,7 +527,7 @@ docs-lint-vale: ## Run Vale linter on documentation
 .PHONY: docs-link-check
 docs-link-check: ## Run markdown-link-check on documentation
 	@command -v markdown-link-check >/dev/null 2>&1 || { echo "markdown-link-check is required but not installed. npm install -g markdown-link-check"; exit 1; }
-	markdown-link-check -c ci/.markdown-link-check.json *.md docs
+	markdown-link-check README.md docs/README.md docs/development.md
 
 .PHONY: docs-lint
 docs-lint: docs-lint-vale docs-link-check ## Run all documentation linters

README.md

@@ -29,7 +29,7 @@ The Operator handles the full lifecycle of ClickHouse clusters, including scalin
 ## Getting Started
 
 ### Prerequisites
-- go version v1.25.0+
+- go version v1.26.0+
 - docker version 17.03+
 - `kubectl` version v1.28.0+
 - Access to a Kubernetes v1.28.0+ cluster

docs/01_overview.md

@@ -0,0 +1,41 @@
+---
+position: 1
+slug: /clickhouse-operator/overview
+title: 'ClickHouse Operator'
+keywords: ['kubernetes']
+description: 'Overview page for the ClickHouse Operator - a Kubernetes operator that automates the deployment, configuration, and management of ClickHouse clusters and ClickHouse Keeper clusters on Kubernetes.'
+doc_type: 'guide'
+sidebar_label: 'Overview'
+---
+
+The ClickHouse Operator is a Kubernetes operator that automates the deployment, configuration, and management of ClickHouse clusters and ClickHouse Keeper clusters on Kubernetes.
+It provides declarative cluster management through custom resources, enabling users to easily create highly-available ClickHouse deployments.
+
+The Operator handles the full lifecycle of ClickHouse clusters including scaling, upgrades, and configuration management.
+
+## Features {#features}
+
+- **ClickHouse Cluster Management**: Create and manage ClickHouse clusters
+- **ClickHouse Keeper Integration**: Built-in support for ClickHouse Keeper clusters for distributed coordination
+- **Storage Provisioning**: Customizable persistent volume claims with storage class selection
+- **High Availability**: Fault tolerant installations for ClickHouse and Keeper clusters
+- **Security**: Built-in security features TLS/SSL support for secure cluster communication
+- **Monitoring**: Prometheus metrics integration for observability
+
+## Installation {#installation}
+
+Choose your preferred installation method:
+
+- [Manifests Installation](./02_install/kubectl.md) - Install using kubectl/kustomize
+- [Helm Installation](./02_install/helm.md) - Install using Helm charts
+- [Operator Lifecycle Manager (OLM) Installation](./02_install/olm.md) - Install using OLM
+
+## Guides {#guides}
+
+- **[Introduction](./03_guides/01_introduction.md)** - General overview of ClickHouse Operator concepts
+- **[Configuration Guide](./03_guides/02_configuration.md)** - Configure ClickHouse and Keeper clusters
+
+## Reference {#reference}
+
+- **[API Reference](./04_api_reference.md)** - Complete API documentation for custom resources
+- **[Source Code](https://github.com/ClickHouse/clickhouse-operator)** - Explore the Operator's source code on GitHub

docs/02_install/_category_.yml

@@ -0,0 +1,4 @@
+position: 2
+label: 'Install'
+collapsible: true
+collapsed: true

docs/installation/helm.md → docs/02_install/helm.md

@@ -1,14 +1,21 @@
-# Installation with Helm
+---
+slug: /clickhouse-operator/install/helm
+title: 'Install the ClickHouse Operator with Helm'
+keywords: ['kubernetes']
+description: 'This guide covers installing the ClickHouse Operator using Helm charts.'
+doc_type: 'guide'
+sidebar_label: 'Helm'
+---
 
 This guide covers installing the ClickHouse Operator using Helm charts.
 
-## Prerequisites
+## Prerequisites {#prerequisites}
 
 - Kubernetes cluster v1.28.0 or later
 - Helm v3.0 or later
 - kubectl configured to communicate with your cluster
 
-## Install Helm
+## Install Helm {#install-helm}
 
 If you don't have Helm installed:
 
@@ -22,14 +29,17 @@ Verify installation:
 helm version
 ```
 
-## Install the Operator
+## Install the Operator {#install-the-operator}
+
+:::note
+By default Helm chart deploys ClickHouse Operator with webhooks enabled and requires cert-manager installed.
+:::
 
-**NOTE:**  By default Helm chart deploys ClickHouse Operator with webhooks enabled and requires cert-manager installed.
 ```bash
 helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-manager --create-namespace --set crds.enabled=true
 ```
 
-### From OCI Helm Repository
+### From OCI Helm repository {#from-oci-helm-repository}
 
 Install the latest release
 ```bash
@@ -46,7 +56,7 @@ Install a specific operator version
        --set-json="manager.container.tag=<operator version>
 ```
 
-### From Local Chart
+### From Local Chart {#from-local-chart}
 
 Clone the repository and install from the local chart:
 
@@ -56,5 +66,6 @@ cd clickhouse-operator
 helm install clickhouse-operator ./dist/chart
 ```
 
-### Configuration Options
-For advanced configuration options, refer to the [values.yaml](../../dist/chart/values.yaml) file in the Helm chart
+### Configuration options {#configuration-options}
+
+For advanced configuration options, refer to the [values.yaml](https://github.com/ClickHouse/clickhouse-operator/blob/main/dist/chart/values.yaml) file in the Helm chart

docs/installation/kubectl.md → docs/02_install/kubectl.md

@@ -1,16 +1,25 @@
-# Installation with kubectl
+---
+slug: /clickhouse-operator/install/kubectl
+title: 'Install the ClickHouse Operator with kubectl'
+keywords: ['kubernetes']
+description: 'This guide covers installing the ClickHouse Operator using kubectl and manifest files.'
+doc_type: 'guide'
+sidebar_label: 'kubectl'
+---
 
 This guide covers installing the ClickHouse Operator using kubectl and manifest files.
 
-## Prerequisites
+## Prerequisites {#prerequisites}
 
 - Kubernetes cluster v1.28.0 or later
 - kubectl v1.28.0 or later
 - Cluster admin permissions
 
-## Install from Release Manifests
+## Install from Release Manifests {#install-from-release-manifests}
 
-**NOTE:** Requires cert-manager to issue webhook certificates.
+:::note
+Requires cert-manager to issue webhook certificates.
+:::
 
 Install the operator and CRDs from the latest release:
 
@@ -27,7 +36,7 @@ This will:
 6. Configure SSL certificates using cert-manager
 7. Enable metrics endpoint
 
-## Verify Installation
+## Verify Installation {#verify-installation}
 
 Check that the operator is running:
 
@@ -36,7 +45,7 @@ kubectl get pods -n clickhouse-operator-system
 ```
 
 Expected output:
-```
+```text
 NAME                                                 READY   STATUS    RESTARTS   AGE
 clickhouse-operator-controller-manager-xxxxxxxxxx    1/1     Running   0          1m
 ```
@@ -48,23 +57,23 @@ kubectl get crd | grep clickhouse.com
 ```
 
 Expected output:
-```
+```text
 clickhouseclusters.clickhouse.com    2025-01-06T00:00:00Z
 keeperclusters.clickhouse.com        2025-01-06T00:00:00Z
 ```
 
-## Configure Custom Deployment Options
+## Configure Custom Deployment Options {#configure-custom-deployment-options}
 
 If you want to configure operator deployment options, follow the steps below.
 
-### 1. Clone the Repository
+### 1. Clone the Repository {#clone-the-repository}
 
 ```bash
 git clone https://github.com/ClickHouse/clickhouse-operator.git
 cd clickhouse-operator
 ```
 
-### 2. Configure installation options
+### 2. Configure installation options {#configure-installation-options}
 
 Edit config/default/kustomization.yaml to enable/disable features as needed.
 
@@ -73,7 +82,7 @@ Edit config/default/kustomization.yaml to enable/disable features as needed.
 * To enable ServiceMonitor for Prometheus Operator, uncomment the `[PROMETHEUS]` section.
 * To enable operator network policies, uncomment the `[NETWORK POLICY]` section.
 
-### 3. Build and Deploy
+### 3. Build and Deploy {#build-and-deploy}
 
 Build the operator manifests and apply them:
 

docs/installation/olm.md → docs/02_install/olm.md

@@ -1,24 +1,24 @@
-# OLM Installation
+---
+slug: /clickhouse-operator/install/olm
+title: 'Install the ClickHouse Operator with Operator Lifecycle Manager (OLM)'
+keywords: ['kubernetes']
+description: 'This guide covers installing the ClickHouse Operator using Operator Lifecycle Manager (OLM).'
+doc_type: 'guide'
+sidebar_label: 'OLM'
+---
 
 This guide covers installing the ClickHouse Operator using Operator Lifecycle Manager (OLM).
 
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Install OLM](#install-olm)
-- [Install the Operator](#install-the-operator)
-- [Uninstall](#uninstall)
-
-## Prerequisites
+## Prerequisites {#prerequisites}
 
 - Kubernetes cluster version 1.28.0 or later
 - kubectl configured to access your cluster
 - Cluster admin permissions
 - Installed OLM (Operator Lifecycle Manager)
 
-## Install OLM
+## Install OLM {#install-olm}
 
-If OLM is not already installed in your cluster, install it:
+If OLM isn't already installed in your cluster, install it:
 
 ```bash
 # Check if OLM is installed
@@ -28,9 +28,9 @@ kubectl get ns olm
 curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh | bash -s v0.28.0
 ```
 
-## Install the Operator
+## Install the Operator {#install-the-operator}
 
-### Install from GitHub Catalog
+### Install from GitHub Catalog {#install-from-github-catalog}
 
 ```bash
 # Create the operator namespace
@@ -77,7 +77,12 @@ spec:
   installPlanApproval: Automatic
 EOF
 ```
-## Uninstall
+
+### Install from OperatorHub {#install-from-operatorhub}
+
+Follow the instructions on the [OperatorHub page for ClickHouse Operator](https://operatorhub.io/operator/clickhouse-operator) to install the operator using OLM.
+
+## Uninstall {#uninstall}
 
 ```bash
 # Delete the subscription
@@ -92,8 +97,9 @@ kubectl delete operatorgroup clickhouse-operator-group -n clickhouse-operator-sy
 # Delete the Operator view
 kubectl delete operator clickhouse-operator.clickhouse-operator-system
 ```
+
 More info about uninstalling can be found in the [OLM documentation](https://olm.operatorframework.io/docs/tasks/uninstall-operator/).
 
-## Additional Resources
+## Additional Resources {#additional-resources}
 
 - [Operator Lifecycle Manager Documentation](https://olm.operatorframework.io/docs)