Fix formatting in docs (#1466)

Mostly fixes lists that render fine in GitHub, but not on
the mkdocs website.

Also replaces several text notes with visual note blocks
like we do in other places across our docs.

Signed-off-by: Mikalai Radchuk <[email protected]>

docs/howto/derive-service-account.md

@@ -21,6 +21,7 @@ The service account must have permissions to:
  - create and manage the extension controller's deployment
 
 Additionally, for clusters that use the [OwnerReferencesPermissionEnforcement](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#ownerreferencespermissionenforcement) admission plug-in, the service account must also have permissions to:
+
  - update finalizers on the ClusterExtension to be able to set blockOwnerDeletion and ownerReferences
 
 It is good security practice to follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), and scope permissions to specific resource names, wherever possible.
@@ -36,17 +37,17 @@ The final permission set can be found in the [ClusterExtension sample manifest](
 The bundle includes the following manifests, which can be found [here](https://github.com/argoproj-labs/argocd-operator/tree/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0):
 
 * `ClusterServiceVersion`:
-  - [argocd-operator.v0.6.0.clusterserviceversion.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator.v0.6.0.clusterserviceversion.yaml)
+    - [argocd-operator.v0.6.0.clusterserviceversion.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator.v0.6.0.clusterserviceversion.yaml)
 * `CustomResourceDefinition`s:
-  - [argoproj.io_applicationsets.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_applicationsets.yaml)
-  - [argoproj.io_applications.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_applications.yaml)
-  - [argoproj.io_appprojects.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_appprojects.yaml)
-  - [argoproj.io_argocdexports.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_argocdexports.yaml)
-  - [argoproj.io_argocds.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_argocds.yaml)
+    - [argoproj.io_applicationsets.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_applicationsets.yaml)
+    - [argoproj.io_applications.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_applications.yaml)
+    - [argoproj.io_appprojects.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_appprojects.yaml)
+    - [argoproj.io_argocdexports.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_argocdexports.yaml)
+    - [argoproj.io_argocds.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argoproj.io_argocds.yaml)
 * Additional resources:
-  - [argocd-operator-controller-manager-metrics-service_v1_service.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-controller-manager-metrics-service_v1_service.yaml)
-  - [argocd-operator-manager-config_v1_configmap.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-manager-config_v1_configmap.yaml)
-  - [argocd-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml)
+    - [argocd-operator-controller-manager-metrics-service_v1_service.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-controller-manager-metrics-service_v1_service.yaml)
+    - [argocd-operator-manager-config_v1_configmap.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-manager-config_v1_configmap.yaml)
+    - [argocd-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml)
 
 The `ClusterServiceVersion` defines a single `Deployment` in `spec.install.deployments` named `argocd-operator-controller-manager` with a `ServiceAccount` of the same name.
 It declares the following cluster-scoped permissions in `spec.install.clusterPermissions`, and its namespace-scoped permissions in `spec.install.permissions`.
@@ -269,6 +270,7 @@ This example's `ClusterServiceVersion` can be found [here](https://github.com/ar
 
 The installer service account must also create and manage other namespace-scoped resources included in the bundle.
 In this example, the bundle also includes two additional namespace-scoped resources:
+
  * the [argocd-operator-controller-manager-metrics-service](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-controller-manager-metrics-service_v1_service.yaml) `Service`, and
  * the [argocd-operator-manager-config](https://github.com/argoproj-labs/argocd-operator/blob/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0/argocd-operator-manager-config_v1_configmap.yaml) `ConfigMap`
 

docs/howto/how-to-grant-api-access.md

@@ -76,7 +76,7 @@ rules:
   - create
   - update
   - patch
-  - delete 
+  - delete
 ```
 
 ### Example: Defining a Custom "Admin" ClusterRole
@@ -94,8 +94,10 @@ rules:
   verbs:
   - '*'
 ```
-**Note**: The `'*'` in verbs allows all actions on the specified resources
-In each case, replace `<your-api-group>` and `<your-custom-resources>` with the actual API group and resource names provided by the installed cluster extension.
+
+!!! note
+    The `'*'` in verbs allows all actions on the specified resources.
+    In each case, replace `<your-api-group>` and `<your-custom-resources>` with the actual API group and resource names provided by the installed cluster extension.
 
 ---
 

docs/project/olmv1_architecture.md

@@ -53,7 +53,8 @@ flowchart TB
     A -- pushed to --> B
 ```
 
-**Note**: The direction of the arrows represents the flow of communication. If an arrow starts from A and points to B, it indicates that A retrieves or consumes information from B, unless otherwise specified.
+!!! note
+    The direction of the arrows represents the flow of communication. If an arrow starts from A and points to B, it indicates that A retrieves or consumes information from B, unless otherwise specified.
 
 ---
 
@@ -91,10 +92,9 @@ catalogd has three main sub-components:
 1. **ClusterCatalog Controller**:
     - Pulls FBC-based catalog images from the registry and unpacks them into the catalog content cache.
     - Reconciles any changes in the catalog and ensures the latest content is reflected in the cluster.
-  
+
 2. **CatalogD HTTP Server**:
     - Serves catalog information to clients, such as the Cluster Extension Controller.
 
 3. **CatalogD Content Cache**:
     - A cache maintained by the Catalog Controller that stores unpacked catalog data, which the CatalogD HTTP Server uses to respond to client queries.
-

docs/project/olmv1_design_decisions.md

@@ -1,8 +1,8 @@
 # Multi-Tenancy Challenges, Lessons Learned, and Design Shifts
 
-This provides historical context on the design explorations and challenges that led to substantial design shifts between 
-OLM v1 and its predecessor. It explains the technical reasons why OLM v1 cannot support major v0 features, such as, 
-multi-tenancy, and namespace-specific controller configurations. Finally, it highlights OLM v1’s shift toward 
+This provides historical context on the design explorations and challenges that led to substantial design shifts between
+OLM v1 and its predecessor. It explains the technical reasons why OLM v1 cannot support major v0 features, such as,
+multi-tenancy, and namespace-specific controller configurations. Finally, it highlights OLM v1’s shift toward
 more secure, predictable, and simple operations while moving away from some of the complex, error-prone features of OLM v0.
 
 ## What won't OLM v1 do that OLM v0 did?
@@ -91,7 +91,7 @@ There is a set of operators that both (a) provide fully namespace-scoped workloa
 
 Some projects have been successful delivering and supporting their operator on Kubernetes, but outside of OLM, for example with helm-packaged operators. On this path, individual layered project teams have more flexibility in solving lifecycling problems for their users because they are unencumbered by OLM’s opinions. However the tradeoff is that those project teams and their users take on responsibility and accountability for safe upgrades, automation, and multi-tenant architectures. With OLM v1 no longer attempting to support multi-tenancy in a first-class way, these tradeoffs change and project teams may decide that a different approach is necessary.
 
-This path does not necessarily mean a scattering of content in various places. It would still be possible to provide customers with a marketplace of content (e.g. see https://artifacthub.io/).
+This path does not necessarily mean a scattering of content in various places. It would still be possible to provide customers with a marketplace of content (e.g. see [artifacthub.io](https://artifacthub.io/)).
 
 ### Authors of "simple" operators ship their workload without an operator
 
@@ -168,6 +168,7 @@ In cases where OLMv0 decides that joint ownership of CRDs will not impact differ
 In OLM v1, we will not design the core APIs and controllers around this promise. Instead, we will build an API where ownership of installed objects is not shared. Managed objects are owned by exactly one extension.
 
 This pattern is generic, aligns with the Kubernetes API, and makes multi-tenancy a possibility, but not a guarantee or core concept. We will explore the implications of this design on existing OLMv0 registry+v1 bundles as part of the larger v0 to v1 migration design. For net new content, operator authors that intend multiple installations of operator on the same cluster would need to package their components to account for this ownership rule. Generally, this would entail separation along these lines:
+
 - CRDs, conversion webhook workloads, and admission webhook configurations and workloads, APIServices and workloads.
 - Controller workloads, service accounts, RBAC, etc.
 
@@ -212,11 +213,11 @@ OLM v1 will take a slightly different approach:
 
 - It will not require bundles to have very specific controller-centric shapes. OLM v1 will happily install a bundle that contains a deployment, service, and ingress or a bundle that contains a single configmap.
 - However for bundles that do include CRDs, controllers, RBAC, webhooks, and other objects that relate to the behavior of the apiserver, OLM will continue to have opinions and special handling:
-  - CRD upgrade checks (best effort)
-  - Specific knowledge and handling of webhooks.
+    - CRD upgrade checks (best effort)
+    - Specific knowledge and handling of webhooks.
 - To the extent necessary OLM v1 will include optional controller-centric concepts in its APIs and or CLIs in order to facilitate the most common controller patterns. Examples could include:
-  - Permission management
-  - CRD upgrade check policies
+    - Permission management
+    - CRD upgrade check policies
 - OLM v1 will continue to have opinions about upgrade traversals and CRD changes that help users prevent accidental breakage, but it will also allow administrators to disable safeguards and proceed anyway.
 
 OLMv0 has some support for automatic upgrades. However, administrators cannot control the maximum version for automatic upgrades, and the upgrade policy (manual vs automatic) applies to all operators in a namespace. If any operator’s upgrade policy is manual, all upgrades of all operators in the namespace must be approved manually.
@@ -260,4 +261,3 @@ Areas where the official CLI could provide value include:
 - Upgrade previews
 - RBAC management
 - Discovery of available APIs
-