📖 restructure docs (#1344)

* 🌱 add new structure

* 🌱 improve heading levels

* 🌱 fix links

* 🌱 add language to codeblocks

* 🌱 add backticks & frontmatter

* 🌱 move docs to caph folder & remove .md extension

* 🌱 fix links

* 🌱 add dummy content

* 🌱 fix links

* 🌱 add introduction

* Populate pages with TODO

* Fix reference to supported versions

* 🌱 fix url

* 🌱 add notes syntax

* 🌱 fix url

* 🌱 add missing callout

* 🌱 fix links & add callouts

* 🌱 fix links

---------

Co-authored-by: Lucas Rattz <lucas.rattz@syself.com>

CONTRIBUTING.md

@@ -23,7 +23,7 @@ Help and contributions are very welcome in the form of code contributions but al
 
 1. If working on an issue, signal other contributors that you are actively working on it by commenting on it. Wait for approval in form of someone assigning you to the issue.
 2. Fork the desired repo, develop and test your code changes.
-    1. See the [Development Guide](docs/developers/development.md) for more instructions on setting up your environment and testing changes locally.
+    1. See the [Development Guide](/docs/caph/04-developers/01-development-guide.md) for more instructions on setting up your environment and testing changes locally.
 3. Submit a pull request.
     1. All code PR must be created in "draft mode". This helps other contributors by not blocking E2E tests, which cannot run in parallel. After your PR is approved, you can mark it "ready for review".
     1.  All code PR must be have a title starting with one of
@@ -41,4 +41,4 @@ Help and contributions are very welcome in the form of code contributions but al
 
 All changes must be code reviewed. Coding conventions and standards are explained in the official [developer docs](https://github.com/kubernetes/community/tree/master/contributors/devel). Expect reviewers to request that you avoid common [go style mistakes](https://github.com/golang/go/wiki/CodeReviewComments) in your PRs.
 
-In case you want to run our E2E tests locally, please refer to [Testing](docs/developers/development.md#submitting-prs-and-testing) guide. 
+In case you want to run our E2E tests locally, please refer to [Testing](/docs/caph/04-developers/01-development-guide.md#submitting-prs-and-testing) guide. 

README.md

@@ -3,9 +3,9 @@
 <br>
 
 <div align="center">
-<a href="docs/topics/quickstart.md">Quickstart</a> |
-<a href="docs/README.md">Docs</a> |
-<a href="docs/developers/development.md">Contribution Guide</a><br><br>
+<a href="/docs/caph/01-getting-started/03-quickstart.md">Quickstart</a> |
+<a href="/docs/README.md">Docs</a> |
+<a href="/docs/caph/04-developers/01-development-guide.md">Contribution Guide</a><br><br>
 <a href="https://cluster-api.sigs.k8s.io/">Cluster API Book</a>
 </div>
 
@@ -77,11 +77,11 @@ If you don't have a dedicated team for managing Kubernetes, you can use [Syself
 
 Ready to dive in? Here are some resources to get you started:
 
-- [**Cluster API Provider Hetzner 15 Minute Tutorial**](docs/topics/quickstart.md): Set up a bootstrap cluster using Kind and deploy a Kubernetes cluster on Hetzner.
-- [**Develop and test Kubernetes clusters with Tilt**](docs/developers/development.md): Start using Tilt for rapid testing of various cluster flavors, like with/without a private network or bare metal.
-- [**Develop and test your own node-images**](docs/topics/node-image.md): Learn how to use your own machine images for production systems.
+- [**Cluster API Provider Hetzner 15 Minute Tutorial**](/docs/caph/01-getting-started/03-quickstart.md): Set up a bootstrap cluster using Kind and deploy a Kubernetes cluster on Hetzner.
+- [**Develop and test Kubernetes clusters with Tilt**](/docs/caph/04-developers/01-development-guide.md): Start using Tilt for rapid testing of various cluster flavors, like with/without a private network or bare metal.
+- [**Develop and test your own node-images**](/docs/caph/02-topics/02-node-image.md): Learn how to use your own machine images for production systems.
 
-In addition to the pure creation and operation of Kubernetes clusters, this provider can also validate and approve certificate signing requests. This increases security as the kubelets of the nodes can be operated with signed certificates, and enables the metrics-server to run securely. [Click here](docs/topics/advanced-caph.md#csr-controller) to read more about the CSR controller.
+In addition to the pure creation and operation of Kubernetes clusters, this provider can also validate and approve certificate signing requests. This increases security as the kubelets of the nodes can be operated with signed certificates, and enables the metrics-server to run securely. [Click here](/docs/caph/02-topics/03-advanced-caph.md#csr-controller) to read more about the CSR controller.
 
 ## 🖇️ Compatibility with Cluster API and Kubernetes Versions
 
@@ -121,21 +121,21 @@ Each version of Cluster API for Hetzner will attempt to support at least two Kub
 > [!NOTE]
 > Cluster API Provider Hetzner relies on a few prerequisites that must be already installed in the operating system images, such as a container runtime, kubelet, and Kubeadm.
 >
-> Reference images are available in kubernetes-sigs/image-builder and [templates/node-image](templates/node-image).
+> Reference images are available in kubernetes-sigs/image-builder and [templates/node-image](/templates/node-image).
 >
-> If pre-installation of these prerequisites isn't possible, [custom scripts can be deployed](docs/topics/node-image through the Kubeadm config.md).
+> If pre-installation of these prerequisites isn't possible, [custom scripts can be deployed](/docs/caph/02-topics/02-node-image) through the Kubeadm config.
 
 ---
 
 ## 📖 Documentation
 
-Documentation can be found in the `/docs` directory. [Here](docs/README.md) is an overview of our documentation.
+Documentation can be found in the `/docs` directory. [Here](/docs/README.md) is an overview of our documentation.
 
 ## 👥 Getting Involved and Contributing
 
 We, maintainers and the community, welcome any contributions to Cluster API Provider Hetzner. For suggestions, contributions, and assistance, contact the maintainers anytime.
 
-To set up your environment, refer to the [development guide](docs/developers/development.md).
+To set up your environment, refer to the [development guide](/docs/caph/04-developers/01-development-guide.md).
 
 For new contributors, check out issues tagged as [`good first issue`][good_first_issue]. These are typically smaller in scope and great for getting familiar with the codebase.
 
@@ -148,7 +148,7 @@ do!
 
 ## ⚖️ Code of Conduct
 
-Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
+Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](/code-of-conduct.md).
 
 ## :shipit: GitHub Issues
 

docs/README.md

@@ -2,27 +2,34 @@
 
 This is the official documentation of Cluster API Provider Hetzner. Before starting with this documentation, you should have a basic understanding of Cluster API. Cluster API is a Kubernetes sub-project focused on providing a declarative API to manage Kubernetes clusters. Refer to the Cluster API quick start guide from their [official documentation](https://cluster-api.sigs.k8s.io/user/quick-start.html).
 
-## Quick start
+## Getting Started
 
-- [Preparation](topics/preparation.md)
-- [Getting started](topics/quickstart.md)
+- [Introduction](/docs/caph/01-getting-started/01-introduction.md)
+- [Preparation](/docs/caph/01-getting-started/02-preparation)
+- [Quickstart](/docs/caph/01-getting-started/03-quickstart)
 
 ## Topics
 
-- [Managing SSH Keys](topics/managing-ssh-keys.md)
-- [Node Images](topics/node-image.md)
-- [Production Environment](topics/production-environment.md)
-- [Advanced CAPH](topics/advanced-caph.md)
-- [Upgrading CAPH](topics/upgrade.md)
+- [Managing SSH Keys](/docs/caph/02-topics/01-managing-ssh-keys)
+- [Node Images](/docs/caph/02-topics/02-node-image)
+- [Production Environment](/docs/caph/02-topics/03-production-environment)
+- [Advanced CAPH](/docs/caph/02-topics/04-advanced-caph)
+- [Upgrading CAPH](/docs/caph/02-topics/05-upgrading-caph)
+- [Hetzner Baremetal](/docs/caph/02-topics/06-hetzner-baremetal)
 
 ## Reference
-- [General](reference/README.md)
-- [HetznerCluster](reference/hetzner-cluster.md)
-- [HCloudMachineTemplate](reference/hcloud-machine-template.md)
-- [HetznerBareMetalHost](reference/hetzner-bare-metal-host.md)
-- [HetznerBareMetalMachineTemplate](reference/hetzner-bare-metal-machine-template.md)
-- [HetznerBareMetalRemediationTemplate](reference/hetzner-bare-metal-remediation-template.md)
+
+- [General](/docs/caph/03-reference/01-introduction)
+- [HetznerCluster](/docs/caph/03-reference/02-hetzner-cluster)
+- [HCloudMachineTemplate](/docs/caph/03-reference/03-hcloud-machine-template)
+- [HCloudMachineTemplate](/docs/caph/03-reference/04-hcloud-remediation-template)
+- [HetznerBareMetalHost](/docs/caph/03-reference/05-hetzner-bare-metal-host)
+- [HetznerBareMetalMachineTemplate](/docs/caph/03-reference/06-hetzner-bare-metal-machine-template)
+- [HetznerBareMetalRemediationTemplate](/docs/caph/03-reference/07-hetzner-bare-metal-remediation-template)
+
 ## Development
-- [Development guide](developers/development.md)
-- [Tilt](developers/tilt.md)
-- [Releasing](developers/releasing.md)
+
+- [Development guide](/docs/caph/04-developers/01-development-guide)
+- [Tilt](/docs/caph/04-developers/02-tilt)
+- [Releasing](/docs/caph/04-developers/03-releasing)
+- [Updating Kubernetes version](/docs/caph/04-developers/04-updating-kubernetes-version)

docs/caph/01-getting-started/01-introduction.md

@@ -0,0 +1,46 @@
+---
+title: Introduction
+---
+
+Welcome to the official documentation for the Cluster API Provider Hetzner (CAPH).
+
+## What is the Cluster API Provider Hetzner
+
+CAPH is a Kubernetes Cluster API provider that facilitates the deployment and management of self-managed Kubernetes clusters on Hetzner infrastructure. The provider supports both cloud and bare-metal instances for consistent, scalable, and production-ready cluster operations.
+
+It is recommended that you have at least a basic understanding of Cluster API before getting started with CAPH. You can refer to the Cluster API Quick Start Guide from its [official documentation](https://cluster-api.sigs.k8s.io).
+
+## Compatibility with Cluster API and Kubernetes Versions
+
+This provider's versions are compatible with the following versions of Cluster API:
+
+|                                   | Cluster API `v1beta1` (`v1.6.x`) | Cluster API `v1beta1` (`v1.7.x`) |
+| --------------------------------- | -------------------------------- | -------------------------------- |
+| Hetzner Provider `v1.0.0-beta.33` | ✅                              | ❌                               |
+| Hetzner Provider `v1.0.0-beta.34-35` | ❌                              | ✅                               |
+
+This provider's versions can install and manage the following versions of Kubernetes:
+
+|                   | Hetzner Provider `v1.0.x` |
+| ----------------- | ------------------------- |
+| Kubernetes 1.23.x | ✅                       |
+| Kubernetes 1.24.x | ✅                       |
+| Kubernetes 1.25.x | ✅                       |
+| Kubernetes 1.26.x | ✅                       |
+| Kubernetes 1.27.x | ✅                       |
+| Kubernetes 1.28.x | ✅                       |
+| Kubernetes 1.29.x | ✅                       |
+| Kubernetes 1.30.x | ✅                       |
+
+Test status:
+
+- ✅ tested
+- ❔ should work, but we weren't able to test it
+
+Each version of Cluster API for Hetzner will attempt to support at least two Kubernetes versions.
+
+{% callout %}
+
+As the versioning for this project is tied to the versioning of Cluster API, future modifications to this policy may be made to more closely align with other providers in the Cluster API ecosystem.
+
+{% /callout %}

docs/topics/preparation.md → docs/caph/01-getting-started/02-preparation.md

@@ -1,4 +1,6 @@
-# Preparation
+---
+title: Preparation
+---
 
 ## Preparation of the Hetzner Project and Credentials
 
@@ -8,14 +10,15 @@ There are several tasks that have to be completed before a workload cluster can
 
 1. Create a new [HCloud project](https://console.hetzner.cloud/projects).
 2. Generate an API token with read and write access. You'll find this if you click on the project and go to "security".
-3. If you want to use it, generate an SSH key, upload the public key to HCloud (also via "security"), and give it a name. Read more about [Managing SSH Keys](managing-ssh-keys.md).
+3. If you want to use it, generate an SSH key, upload the public key to HCloud (also via "security"), and give it a name. Read more about [Managing SSH Keys](/docs/caph/02-topics/01-managing-ssh-keys).
 
 ### Preparing Hetzner Robot
 
 1. Create a new web service user. [Here](https://robot.your-server.de/doc/webservice/en.html#preface), you can define a password and copy your user name
 2. Generate an SSH key. You can either upload it via Hetzner Robot UI or just rely on the controller to upload a key that it does not find in the robot API. This is possible, as you have to store the public and private key together with the SSH key's name in a secret that the controller reads.
 
 ---
+
 ## Bootstrap or Management Cluster Installation
 
 ### Common Prerequisites
@@ -33,20 +36,23 @@ It is a common practice to create a temporary, local bootstrap cluster, which is
 
 #### 1. Existing Management Cluster.
 
-For production use, a “real” Kubernetes cluster should be used with appropriate backup and Disaster Recovery policies and procedures in place. The Kubernetes cluster must be at least a [supported version](../../README.md#fire-compatibility-with-cluster-api-and-kubernetes-versions).
+For production use, a “real” Kubernetes cluster should be used with appropriate backup and Disaster Recovery policies and procedures in place. The Kubernetes cluster must be at least a [supported version](https://github.com/syself/cluster-api-provider-hetzner/blob/main/README.md#%EF%B8%8F-compatibility-with-cluster-api-and-kubernetes-versions).
 
 #### 2. Kind.
 
 [kind](https://kind.sigs.k8s.io/) can be used for creating a local Kubernetes cluster for development environments or for the creation of a temporary bootstrap cluster used to provision a target management cluster on the selected infrastructure provider.
 
 ---
+
 ## Install Clusterctl and initialize Management Cluster
 
 ### Install Clusterctl
+
 Please use the instructions here: https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl
 or use: `make clusterctl`
 
 ### Initialize the management cluster
+
 Now that we’ve got clusterctl installed and all the prerequisites are in place, we can transform the Kubernetes cluster into a management cluster by using the `clusterctl init` command. More information about clusterctl can be found [here](https://cluster-api.sigs.k8s.io/clusterctl/commands/commands.html).
 
 For the latest version:
@@ -59,6 +65,7 @@ clusterctl init --core cluster-api --bootstrap kubeadm --control-plane kubeadm -
 or for a specific [version](https://github.com/syself/cluster-api-provider-hetzner/releases): `--infrastructure hetzner:vX.X.X`
 
 ---
+
 ## Variable Preparation to generate a cluster-template.
 
 ```shell
@@ -72,14 +79,14 @@ export HCLOUD_CONTROL_PLANE_MACHINE_TYPE=cpx31 \
 export HCLOUD_WORKER_MACHINE_TYPE=cpx31
 ```
 
-* HCLOUD_SSH_KEY: The SSH Key name you loaded in HCloud.
-* HCLOUD_REGION: https://docs.hetzner.com/cloud/general/locations/
-* HCLOUD_IMAGE_NAME: The Image name of your operating system.
-* HCLOUD_X_MACHINE_TYPE: https://www.hetzner.com/cloud#pricing
+- HCLOUD_SSH_KEY: The SSH Key name you loaded in HCloud.
+- HCLOUD_REGION: https://docs.hetzner.com/cloud/general/locations/
+- HCLOUD_IMAGE_NAME: The Image name of your operating system.
+- HCLOUD_X_MACHINE_TYPE: https://www.hetzner.com/cloud#pricing
 
-For a list of all variables needed for generating a cluster manifest (from the cluster-template.yaml), use `clusterctl generate cluster --infrastructure hetzner:<caph-version> --list-variables hetzner-cluster`:
+For a list of all variables needed for generating a cluster manifest (from the cluster-template.yaml), use `clusterctl generate cluster --infrastructure hetzner:<caph-version> --list-variables hetzner-cluster`
 
-```
+```shell
 $ clusterctl generate cluster --infrastructure hetzner:<caph-version> --list-variables hetzner-cluster
 Required Variables:
   - HCLOUD_CONTROL_PLANE_MACHINE_TYPE
@@ -96,9 +103,10 @@ Optional Variables:
 
 ### Create a secret for hcloud only
 
-In order for the provider integration hetzner to communicate with the Hetzner API ([HCloud API](https://docs.hetzner.cloud/), we need to create a secret with the access data. The secret must be in the same namespace as the other CRs.
+In order for the provider integration hetzner to communicate with the Hetzner API ([HCloud API](https://docs.hetzner.cloud/)), we need to create a secret with the access data. The secret must be in the same namespace as the other CRs.
 
 `export HCLOUD_TOKEN="<YOUR-TOKEN>" `
+
 - HCLOUD_TOKEN: The project where your cluster will be placed. You have to get a token from your HCloud Project.
 
 ```shell
@@ -140,4 +148,4 @@ kubectl patch secret robot-ssh -p '{"metadata":{"labels":{"clusterctl.cluster.x-
 
 The secret name and the tokens can also be customized in the cluster template.
 
-See [node-image](./node-image.md) for more information.
+See [node-image](/docs/caph/02-topics/02-node-image) for more information.