Improve formatting on the docs website (#1446)

Fixes a number of formatting/rendering issues. Mostly around
lists, admonitions (notes, warnings, etc) and collapsible text.

Signed-off-by: Mikalai Radchuk <mradchuk@redhat.com>

Author: m1kola

CONTRIBUTING.md

@@ -43,28 +43,28 @@ you can follow the steps below to test your changes:
 
 1. Create the cluster:
 
-```sh
-kind create cluster operator-controller
-```
+    ```sh
+    kind create cluster operator-controller
+    ```
 
 2. Build your changes:
 
-```sh
-make build docker-build
-```
+    ```sh
+    make build docker-build
+    ```
 
 3. Load the image locally and Deploy to Kind
 
-```sh
-make kind-load kind-deploy
-```
+    ```sh
+    make kind-load kind-deploy
+    ```
 
 ### Communication Channels
 
 - Email: [operator-framework-olm-dev](mailto:operator-framework-olm-dev@googlegroups.com)
 - Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2)
 - Google Group: [olm-gg](https://groups.google.com/g/operator-framework-olm-dev)
-- Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) 
+- Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
 
 ## How are Milestones Designed?
 
@@ -91,7 +91,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec
 
 ## Submitting Issues
 
-Unsure where to submit an issue? 
+Unsure where to submit an issue?
 
 - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
 - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.

docs/concepts/controlling-catalog-selection.md

@@ -159,70 +159,71 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
 
 1. **Create or Update `ClusterCatalogs` with Appropriate Labels and Priority**
 
-   ```yaml
-   apiVersion: olm.operatorframework.io/v1
-   kind: ClusterCatalog
-   metadata:
-     name: catalog-a
-     labels:
-       example.com/support: "true"
-   spec:
-     priority: 1000
-     source:
-       type: Image
-       image:
-         ref: quay.io/example/content-management-a:latest
-   ```
-
-   ```yaml
-   apiVersion: olm.operatorframework.io/v1
-   kind: ClusterCatalog
-   metadata:
-     name: catalog-b
-     labels:
-       example.com/support: "false"
-   spec:
-     priority: 500
-     source:
-       type: Image
-       image:
-         ref: quay.io/example/content-management-b:latest
-   ```
-   NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
+    ```yaml
+    apiVersion: olm.operatorframework.io/v1
+    kind: ClusterCatalog
+    metadata:
+      name: catalog-a
+      labels:
+        example.com/support: "true"
+    spec:
+      priority: 1000
+      source:
+        type: Image
+        image:
+          ref: quay.io/example/content-management-a:latest
+    ```
+
+    ```yaml
+    apiVersion: olm.operatorframework.io/v1
+    kind: ClusterCatalog
+    metadata:
+      name: catalog-b
+      labels:
+        example.com/support: "false"
+    spec:
+      priority: 500
+      source:
+        type: Image
+        image:
+          ref: quay.io/example/content-management-b:latest
+    ```
+    !!! note
+        An `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
 
 
 2. **Create a `ClusterExtension` with Catalog Selection**
 
-   ```yaml
-   apiVersion: olm.operatorframework.io/v1
-   kind: ClusterExtension
-   metadata:
-     name: install-my-operator
-   spec:
-     packageName: my-operator
-     catalog:
-       selector:
-         matchLabels:
-           example.com/support: "true"
-   ```
+    ```yaml
+    apiVersion: olm.operatorframework.io/v1
+    kind: ClusterExtension
+    metadata:
+      name: install-my-operator
+    spec:
+      packageName: my-operator
+      catalog:
+        selector:
+          matchLabels:
+            example.com/support: "true"
+    ```
 
 3. **Apply the Resources**
 
-   ```shell
-   kubectl apply -f content-management-a.yaml
-   kubectl apply -f content-management-b.yaml
-   kubectl apply -f install-my-operator.yaml
-   ```
+    ```shell
+    kubectl apply -f content-management-a.yaml
+    kubectl apply -f content-management-b.yaml
+    kubectl apply -f install-my-operator.yaml
+    ```
 
 4. **Verify the Installation**
 
-   Check the status of the `ClusterExtension`:
+    Check the status of the `ClusterExtension`:
 
-   ```shell
-   kubectl get clusterextension install-my-operator -o yaml
-   ```
+    ```shell
+    kubectl get clusterextension install-my-operator -o yaml
+    ```
 
-   The status should indicate that the bundle was resolved from `catalog-a` due to the higher priority and matching label.
+    The status should indicate that the bundle was resolved from `catalog-a` due to the higher priority and matching label.
 
 ## Important Notes
 

docs/concepts/upgrade-support.md

@@ -17,10 +17,12 @@ When determining upgrade edges, also known as upgrade paths or upgrade constrain
 
 By supporting legacy OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately.
 
-* If there are multiple possible successors, OLM v1 behavior differs in the following ways:
-  * In legacy OLM, the successor closest to the channel head is chosen.
-  * In OLM v1, the successor with the highest semantic version (semver) is chosen.
-* Consider the following set of file-based catalog (FBC) channel entries:
+If there are multiple possible successors, OLM v1 behavior differs in the following ways:
+
+* In legacy OLM, the successor closest to the channel head is chosen.
+* In OLM v1, the successor with the highest semantic version (semver) is chosen.
+
+Consider the following set of file-based catalog (FBC) channel entries:
 
   ```yaml
   # ...
@@ -51,7 +53,7 @@ spec:
   version: "<version_or_version_range>"
 ```
 
-where setting the `upgradeConstraintPolicy` to:
+Setting the `upgradeConstraintPolicy` to:
 
 `SelfCertified`
 :   Does not limit the next version to the set of successors, and instead allows for any downgrade, sidegrade, or upgrade.
@@ -63,8 +65,8 @@ where setting the `upgradeConstraintPolicy` to:
 
 OLM supports Semver to provide a simplified way for package authors to define compatible upgrades. According to the Semver standard, releases within a major version (e.g. `>=1.0.0 <2.0.0`) must be compatible. As a result, package authors can publish a new package version following the Semver specification, and OLM assumes compatibility. Package authors do not have to explicitly define upgrade edges in the catalog.
 
-> [!NOTE]
-> Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
+!!! note
+    Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
 
 ### Upgrades within the major version zero
 
@@ -77,7 +79,8 @@ You must verify and perform upgrades manually in cases where automatic upgrades
 
 ## Manually verified upgrades and downgrades
 
-**Warning:** If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.
+!!! warning
+    If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.
 
 As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource.
 

docs/contribute/developer.md

@@ -3,10 +3,10 @@
 
 The following `make run` starts a [KIND](https://sigs.k8s.io/kind) cluster for you to get a local cluster for testing, see the manual install steps below for how to run against a remote cluster.
 
-> [!NOTE]
-> You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.
-> 
-> If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
+!!! note
+    You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.
+
+    If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
 
 ### Quickstart Installation
 
@@ -20,9 +20,9 @@ This will build a local container image of the operator-controller, create a new
 
 ### To Install Any Given Release
 
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
+!!! warning
+    Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
+    may affect an existing installation of cert-manager and cause cluster instability.
 
 The latest version of Operator Controller can be installed with the following command:
 
@@ -33,21 +33,21 @@ curl -L -s https://github.com/operator-framework/operator-controller/releases/la
 ### Manual Step-by-Step Installation
 1. Install Instances of Custom Resources:
 
-```sh
-kubectl apply -f config/samples/
-```
+    ```sh
+    kubectl apply -f config/samples/
+    ```
 
 2. Build and push your image to the location specified by `IMG`:
 
-```sh
-make docker-build docker-push IMG=<some-registry>/operator-controller:tag
-```
+    ```sh
+    make docker-build docker-push IMG=<some-registry>/operator-controller:tag
+    ```
 
 3. Deploy the controller to the cluster with the image specified by `IMG`:
 
-```sh
-make deploy IMG=<some-registry>/operator-controller:tag
-```
+    ```sh
+    make deploy IMG=<some-registry>/operator-controller:tag
+    ```
 
 ### Uninstall CRDs
 To delete the CRDs from the cluster:
@@ -72,7 +72,8 @@ make manifests
 
 ---
 
-**NOTE:** Run `make help` for more information on all potential `make` targets.
+!!! note
+    Run `make help` for more information on all potential `make` targets.
 
 ### Rapid Iterative Development with Tilt
 
@@ -124,17 +125,18 @@ This is typically as short as:
 tilt up
 ```
 
-**NOTE:** if you are using Podman, at least as of v4.5.1, you need to do this:
+!!! note
+    If you are using Podman, at least as of v4.5.1, you need to do this:
 
-```shell
-DOCKER_BUILDKIT=0 tilt up
-```
+    ```shell
+    DOCKER_BUILDKIT=0 tilt up
+    ```
 
-Otherwise, you'll see an error when Tilt tries to build your image that looks similar to:
+    Otherwise, you'll see an error when Tilt tries to build your image that looks similar to:
 
-```text
-Build Failed: ImageBuild: stat /var/tmp/libpod_builder2384046170/build/Dockerfile: no such file or directory
-```
+    ```text
+    Build Failed: ImageBuild: stat /var/tmp/libpod_builder2384046170/build/Dockerfile: no such file or directory
+    ```
 
 When Tilt starts, you'll see something like this in your terminal:
 

docs/getting-started/olmv1_getting_started.md

@@ -2,9 +2,9 @@
 
 The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
 
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
+!!! warning
+    Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
+    may affect an existing installation of cert-manager and cause cluster instability.
 
 The latest version of Operator Controller can be installed with the following command:
 

docs/howto/catalog-queries.md

@@ -1,7 +1,8 @@
 # Catalog queries
 
-**Note:** By default, Catalogd is installed with TLS enabled for the catalog webserver.
-The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag.
+!!! note
+    By default, Catalogd is installed with TLS enabled for the catalog webserver.
+    The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag.
 
 
 You can use the `curl` command with `jq` to query catalogs that are installed on your cluster.