docs: move build instructions from Antora into Markdown (#396)

Author: fhennig

.readme/partials/main.md.j2

@@ -10,6 +10,10 @@ You can install the operator using [stackablectl or helm](https://docs.stackable
 
 Read on to get started with it, or see it in action in one of our [demos](https://stackable.tech/en/demos/).
 
+## Building
+
+As a user you do not need to build the operator yourself, but for development purposes you can read the [build instructions](./BUILDING.md) to learn how to build the operator.
+
 ## Getting Started
 
 You can follow this [tutorial](https://docs.stackable.tech/home/stable/{{operator_docs_slug}}/getting_started/first_steps) .

docs/modules/secret-operator/pages/building.adoc renamed to BUILDING.md

@@ -1,20 +1,19 @@
-= Building the Operator
+# Building the Operator
 
 This operator is written in Rust.
 
 It is developed against the latest stable Rust release, and we currently don't support any older versions.
 
-However, the Secret Operator is a https://github.com/container-storage-interface/spec/blob/master/spec.md[Container Storage Interface (CSI)] provider plugin
+However, the Secret Operator is a [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) provider plugin
 for the local Kubelet, which means that it should only be executed inside of a Kubernetes `Pod`. We currently support two ways of building the
-Secret Operator: `docker build` and https://nixos.org/[Nix]. `docker build` is currently our primary deployment target, and our official images are built
+Secret Operator: `docker build` and [Nix](https://nixos.org/). `docker build` is currently our primary deployment target, and our official images are built
 using it. However, Nix has much faster incremental build and deploy times, making it ideal for local development.
 
-== Docker
+## Docker
 
 To build and deploy to the active Kind cluster, run:
 
-[source,console]
-----
+```shell
 $ echo Building with Docker
 # Ensure that all submodules are up-to-date
 $ git submodule update --recursive --init
@@ -31,14 +30,13 @@ $ docker run --rm "$REPO:$TAG" crd | kubectl apply -f-
 $ helm upgrade secret-operator deploy/helm/secret-operator \
        --install \
        --set-string "image.repository=$REPO,image.tag=$TAG"
-----
+```
 
-== Nix
+## Nix
 
 To build and deploy to the active Kind cluster, run the following Bash commands:
 
-[source,console]
-----
+```shell
 $ echo Building with Nix
 # Ensure that all submodules are up-to-date
 $ git submodule update --recursive --init
@@ -59,39 +57,37 @@ $ kubectl apply -f result/crds.yaml
 $ helm upgrade secret-operator deploy/helm/secret-operator \
   --install \
   --set-string "image.repository=$(cat result/image-repo),image.tag=$(cat result/image-tag)"
-----
+```
 
 You may need to add `extra-experimental-features = nix-command` to `/etc/nix/nix.conf`, or add `--experimental-features nix-command` to the Nix commands.
 
-You can also use https://tilt.dev/[Tilt] to automatically rebuild and redeploy when files are changed:
+You can also use [Tilt](https://tilt.dev/) to automatically rebuild and redeploy when files are changed:
 
-[source,console]
-----
+```shell
 $ nix run -f . tilt up
-----
+```
 
-== K3d
+## K3d
 
 Secret-Operator, as with most CSI providers, requires the Kubernetes node's root folder to be mounted as `rshared`. K3d does not do this by default,
 but can be prodded into doing this by running `mount --make-rshared /` in each node container.
 
 To do this for each running node K3d node, run the following script:
 
-[source,console]
-----
+```shell
 for i in $(k3d node list -o json | jq -r .[].name); do
   docker exec -it $i mount --make-rshared /
 done
-----
+```
 
-NOTE: This is _not_ persistent, and must be re-executed every time the cluster (or a node in it) is restarted.
+> [!IMPORTANT]
+> This is _not_ persistent, and must be re-executed every time the cluster (or a node in it) is restarted.
 
-== Local builds
+## Local builds
 
 Local builds (outside of the tools mentioned above) require the openssl, krb5, and Clang libraries, as well as
 pkg-config and protoc. On Ubuntu, this means running:
 
-[source,console]
-----
+```shell
 $ sudo apt install libssl-dev libkrb5-dev libclang-dev pkg-config protobuf-compiler
-----
+```

README.md

@@ -20,6 +20,10 @@ You can install the operator using [stackablectl or helm](https://docs.stackable
 
 Read on to get started with it, or see it in action in one of our [demos](https://stackable.tech/en/demos/).
 
+## Building
+
+As a user you do not need to build the operator yourself, but for development purposes you can read the [build instructions](./BUILDING.md) to learn how to build the operator.
+
 ## Getting Started
 
 You can follow this [tutorial](https://docs.stackable.tech/home/stable/secret-operator/getting_started/first_steps) .

docs/modules/secret-operator/pages/installation.adoc

@@ -56,7 +56,3 @@ In some cases IBM cloud has the kubelet directory located at `/var/data/kubelet/
 `failed to publish volume error=status: Unavailable, message: "failed to create secret parent dir /var/data/kubelet/pods/<POD_ID>/volumes/kubernetes.io~csi/pvc-<PVC_ID>/mount: No such file or directory (os error 2)"`
 
 In case you are encountering the mentioned error (or secret-operator does not work on your IBM cloud at all), you need to add the argument `--set kubeletDir=/var/data/kubelet` to the `helm install` command.
-
-== Building the operator from source
-
-See xref:building.adoc[] for more information.

docs/modules/secret-operator/partials/nav.adoc

@@ -1,6 +1,5 @@
 // the nav list should contain the module, because it will/might
 // be included from a different module
-* xref:secret-operator:building.adoc[]
 * xref:secret-operator:installation.adoc[]
 * xref:secret-operator:usage.adoc[]
 * Concepts