From 9c6e6c0e1c6bf8f6117fe0d20474e6aba70d023a Mon Sep 17 00:00:00 2001
From: Guilherme Cassolato <guicassolato@gmail.com>
Date: Wed, 8 Nov 2023 18:02:43 +0100
Subject: [PATCH] Markdown in HTML blocks

---
 README.md                                     | 28 +++++++++----------
 docs/contributing.md                          | 21 ++++++++------
 docs/getting-started.md                       | 12 ++++----
 docs/user-guides/anonymous-access.md          |  2 +-
 docs/user-guides/api-key-authentication.md    |  2 +-
 ...ed-rate-limiting-envoy-dynamic-metadata.md |  2 +-
 docs/user-guides/authzed.md                   |  2 +-
 docs/user-guides/caching.md                   |  2 +-
 .../deny-with-redirect-to-login.md            |  2 +-
 ...cation-architecture-festival-wristbands.md |  2 +-
 .../envoy-jwt-authn-and-authorino.md          |  2 +-
 docs/user-guides/external-metadata.md         |  2 +-
 docs/user-guides/http-basic-authentication.md |  2 +-
 docs/user-guides/injecting-data.md            |  2 +-
 .../json-pattern-matching-authorization.md    |  2 +-
 .../keycloak-authorization-services.md        |  2 +-
 .../kubernetes-subjectaccessreview.md         |  4 +--
 docs/user-guides/kubernetes-tokenreview.md    |  2 +-
 docs/user-guides/mtls-authentication.md       |  2 +-
 .../user-guides/oauth2-token-introspection.md |  2 +-
 docs/user-guides/observability.md             | 18 ++++++------
 docs/user-guides/oidc-jwt-authentication.md   |  2 +-
 docs/user-guides/oidc-rbac.md                 |  2 +-
 docs/user-guides/oidc-user-info.md            |  2 +-
 docs/user-guides/opa-authorization.md         |  2 +-
 docs/user-guides/passing-credentials.md       |  2 +-
 .../resource-level-authorization-uma.md       |  2 +-
 docs/user-guides/sharding.md                  |  2 +-
 docs/user-guides/token-normalization.md       |  2 +-
 docs/user-guides/validating-webhook.md        |  2 +-
 30 files changed, 68 insertions(+), 65 deletions(-)

diff --git a/README.md b/README.md
index c7b795f7..bed79187 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,7 @@ Under the hood, Authorino is based on Kubernetes [Custom Resource Definitions](h
 9. If authorized, Envoy triggers other HTTP filters in the chain (if any), pre-injecting eventual dynamic metadata returned by Authorino, and ultimately redirects the request to the _Upstream_
 10. The _Upstream_ serves the requested resource to the consumer
 
-<details>
+<details markdown="1">
   <summary>More</summary>
 
   The [Architecture](./docs/architecture.md) section of the docs covers details of protecting your APIs with Envoy and Authorino, including information about topology (centralized gateway, centralized authorization service or sidecars), deployment modes (cluster-wide reconciliation vs. namespaced instances), an specification of Authorino's [`AuthConfig`](./docs/architecture.md#the-authorino-authconfig-custom-resource-definition-crd) Custom Resource Definition (CRD) and more.
@@ -229,7 +229,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 
 ## FAQ
 
-<details>
+<details markdown="1">
   <summary><strong>Do I need to deploy Envoy?</strong></summary>
 
   Authorino is built from the ground up to work well with Envoy. It is strongly recommended that you leverage Envoy along side Authorino. That said, it is possible to use Authorino without Envoy.
@@ -243,7 +243,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   Check out [Kuadrant](https://github.com/kuadrant/kuadrant-controller) for easy-to-use Envoy and Authorino deployment & configuration for API management use-cases, using Kubernetes Custom Resources.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Is Authorino an Identity Provider (IdP)?</strong></summary>
 
   No, Authorino is not an Identity Provider (IdP). Neither it is an auth server of any kind, such as an OAuth2 server, an OpenID Connect (OIDC) server, a Single Sign On (SSO) server.
@@ -254,7 +254,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 </details>
 
 
-<details>
+<details markdown="1">
   <summary><strong>How does Authorino compare to Keycloak?</strong></summary>
 
   Keycloak is a proper auth server and identity provider (IdP). It offers a huge set of features for managing identities, identity sources with multiple user federation options, and a platform for authentication and authorization services.
@@ -266,7 +266,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   You can also use Keycloak for storing auth-relevant resource metadata. These can be fetched by Authorino in request-time, to be combined into your authorization policies. See Keycloak Authorization Services and User-Managed Access (UMA) support, as well as Authorino [UMA external metadata](./docs/features.md#user-managed-access-uma-resource-registry-metadatauma) counter-part.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Why doesn't Authorino handle OAuth flows?</strong></summary>
 
   It has to do with trust. OAuth grants are supposed to be negotiated directly between whoever owns the long-lived credentials in one hand (user, service accounts), and the trustworthy auth server that receives those credentials – ideally with minimum number of hops in the middle – and exchanges them for short-lived access tokens, on the other end.
@@ -274,7 +274,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   There are use-cases for Authorino running in the edge (e.g. Edge Authentication Architecture and token normalization), but in most cases Authorino should be seen as a last-mile component that provides decoupled identity verification and authorization policy enforcement to protected services in request-time. In this sense, the OAuth grant is a pre-flight exchange that happens once and as direct and safe as possible, whereas auth enforcement is kept lightweight and efficient.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Where does Authorino store users and roles?</strong></summary>
 
   Authorino does not store users, roles, role bindings, access control lists, or any raw authorization data. Authorino handles policies, where even these policies can be stored elsewhere (as opposed to stated inline inside of an Authorino `AuthConfig` CR).
@@ -284,7 +284,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In the case of authentication with API keys, as well as its derivative to model HTTP Basic Auth, user data are stored in Kubernetes `Secret`s. The secret's keys, annotations and labels are usually the structures used to organize the data that later a policy evaluated in Authorino may require. Strictly, those are not Authorino data structures.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can't I just use Envoy JWT Authentication and RBAC filters?</strong></summary>
 
   Envoy's [JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto.html) works pretty much similar to Authorino's [JOSE/JWT verification and validation for OpenID Connect](./docs/features.md#jwt-verification-authenticationjwt). In both cases, the JSON Web Key Sets (JWKS) to verify the JWTs are auto-loaded and cached to be used in request-time. Moreover, you can configure for details such as where to extract the JWT from the HTTP request (header, param or cookie) and do some cool tricks regarding how dynamic metadata based on JWT claims can be injected to consecutive filters in the chain.
@@ -296,7 +296,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In summary, Envoy's JWT Authentication and Envoy RBAC filter are excellent solutions for simple use-cases where JWTs from one single issuer is the only authentication method you are planning to support and limited to no authorization rules suffice. On the other hand, if you need to integrate more identity sources, different types of authentication, authorization policies, etc, you might to consider Authorino.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Should I use Authorino if I already have Istio configured?</strong></summary>
 
   Istio is a great solution for managing service meshes. It delivers an excellent platform with an interesting layer of abstraction on top of Envoy proxy's virtual omnipresence within the mesh.
@@ -322,7 +322,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   The good news is that, if you have Istio configured, then you have Envoy and the whole platform for wiring Authorino up if you want to. 😉
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Do I have to learn OPA/Rego language to use Authorino?</strong></summary>
 
   No, you do not. However, if you are comfortable with [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) from Open Policy Agent (OPA), there are some quite interesting things you can do in Authorino, just as you would in any OPA server or OPA plugin, but leveraging Authorino's [built-in OPA module](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) instead. Authorino's OPA module is compiled as part of Authorino's code directly from the Golang packages, and imposes no extra latency to the evaluation of your authorization policies. Even the policies themselves are pre-compiled in reconciliation-time, for fast evaluation afterwards, in request-time.
@@ -334,7 +334,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   Authorino also packages well-established industry standards and protocols for identity verification (JOSE/JWT validation, OAuth token introspection, Kubernetes TokenReview) and ad-hoc request-time metadata fetching (OIDC userinfo, User-Managed Access (UMA)), and corresponding layers of caching, without which such functionalities would have to be implemented by code.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I use Authorino to protect non-REST APIs?</strong></summary>
 
   Yes, you can. In principle, the API format (REST, gRPC, GraphQL, etc) should not matter for the authN/authZ enforcer. There are a couple points to consider though.
@@ -353,13 +353,13 @@ For a detailed description of the features above, refer to the [Features](./docs
   Check out Authorino [OPA authorization](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) and the Rego [Encoding](https://www.openpolicyagent.org/docs/latest/policy-reference/#encoding) functions for options to parse serialized JSON, YAML and URL-encoded params. For XML transformation, an external parsing service connected via Authorino's [HTTP GET/GET-by-POST external metadata](./docs/features.md#http-getget-by-post-metadatahttp) might be required.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I run Authorino other than on Kubernetes?</strong></summary>
 
   As of today, no, you cannot, or at least it wouldn't suit production requirements.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Do I have to be admin of the cluster to install Authorino?</strong></summary>
 
   To install the Authorino Custom Resource Definition (CRD) and to define cluster roles required by the Authorino service, admin privilege to the Kubernetes cluster is required. This step happens only once per cluster and is usually equivalent to installing the [Authorino Operator](https://github.com/kuadrant/authorino-operator).
@@ -367,7 +367,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   Thereafter, deploying instances of the Authorino service and applying `AuthConfig` custom resources to a namespace depend on the permissions set by the cluster administrator – either directly by editing the bindings in the cluster's RBAC, or via options of the operator. In most cases, developers will be granted permissions to create and manage `AuthConfig`s, and sometimes to deploy their own instances of Authorino.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Is it OK to store AuthN/AuthZ configs as Kubernetes objects?</strong></summary>
 
   Authorino's API checks all the bullets to be [aggregated to the Kubernetes cluster APIs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#should-i-add-a-custom-resource-to-my-kubernetes-cluster), and therefore using Custom Resource Definition (CRD) and the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator) has always been an easy design decision.
@@ -381,7 +381,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In other words, there are lots of benefits of using Kubernetes custom resources and custom controllers, and unless you are planning on bursting your server with more services than it can keep record, it is totally 👍 to store your AuthN/AuthZ configs as cluster API objects.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I use Authorino for rate limiting?</strong></summary>
 
   You can, but you shouldn't. Check out instead [Limitador](https://github.com/kuadrant/limitador), for simple and efficient global rate limiting. Combine it with Authorino and Authorino's support for [Envoy Dynamic Metadata](./docs/features.md#envoy-dynamic-metadata) for authenticated rate limiting.
diff --git a/docs/contributing.md b/docs/contributing.md
index 3ed70453..9a510f66 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -30,7 +30,7 @@ The following tools can be installed as part of the development workflow:
   - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests
   - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying
   - [setup-envtest](https://v0-19-x.sdk.operatorframework.io/docs/golang/references/env-test-setup): for running the tests – extra tools installed to `./testbin`
-  - [benchstat]https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports
+  - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports
   - [mockgen](https://github.com/golang/mock/mockgen): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go`
   - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes
 
@@ -113,7 +113,7 @@ Once the deployment is ready, you can forward the requests on port 8000 to the E
 kubectl port-forward deployment/envoy 8000:8000 &
 ```
 
-<details>
+<details markdown="1">
   <summary>Pro tips</summary>
 
   1. Change the default workload namespace by supplying the `NAMESPACE` argument to your `make local-setup` and other deployment, apps and local cluster related targets. If the namespace does not exist, it will be created.
@@ -125,7 +125,7 @@ kubectl port-forward deployment/envoy 8000:8000 &
 
 #### Additional tools (for specific use-cases)
 
-<details>
+<details markdown="1">
   <summary><strong>Limitador</strong></summary>
 
   To deploy [Limitador](https://github.com/kuadrant/limitador) – pre-configured in Envoy for rate-limiting the Talker API to 5 hits per minute per `user_id` when available in the cluster workload –, run:
@@ -135,10 +135,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Keycloak</strong></summary>
 
-  Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup:<br/>
+  Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup:
+
   - Admin console: http://localhost:8080/auth/admin (admin/p)
   - Preloaded realm: **kuadrant**
   - Preloaded clients:
@@ -171,10 +172,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Dex</strong></summary>
 
-  Authorino examples include a bundle of [Dex](https://dexidp.io) preloaded with the following setup:<br/>
+  Authorino examples include a bundle of [Dex](https://dexidp.io) preloaded with the following setup:
+
   - Preloaded clients:<br/>
     - **demo**: to which API consumers delegate access and therefore the one which access tokens are issued to (Client secret: aaf88e0e-d41d-4325-a068-57c4b0d61d8e)
   - Preloaded users:<br/>
@@ -193,10 +195,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>a12n-server</strong></summary>
 
-  Authorino examples include a bundle of [**a12n-server**](https://github.com/curveball/a12n-server) and corresponding MySQL database, preloaded with the following setup:<br/>
+  Authorino examples include a bundle of [**a12n-server**](https://github.com/curveball/a12n-server) and corresponding MySQL database, preloaded with the following setup:
+
   - Admin console: http://a12n-server:8531 (admin/123456)
   - Preloaded clients:<br/>
     - **service-account-1**: to obtain access tokens via `client_credentials` OAuth2 grant type, to consume the Talker API (Client secret: DbgXROi3uhWYCxNUq_U1ZXjGfLHOIM8X3C2bJLpeEdE); includes metadata privilege: `{ "talker-api": ["read"] }` that can be used to write authorization policies
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 34dbb85b..0ba79b2d 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -18,7 +18,7 @@ These are the platform requirements to use Authorino:
 
 - [**Kubernetes**](https://kubernetes.io) server (recommended v1.20 or later), with permission to create Kubernetes Custom Resource Definitions (CRDs) (for bootstrapping Authorino and Authorino Operator)
 
-  <details>
+  <details markdown="1">
     <summary>Alternative: K8s distros and platforms</summary>
 
     Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as <a href="https://www.openshift.com">Red Hat OpenShift</a>, <a href="https://www.ibm.com/cloud/kubernetes-service">IBM Cloud Kubernetes Service (IKS)</a>, <a href="http://cloud.google.com/kubernetes-engine">Google Kubernetes Engine (GKE)</a>, <a href="https://aws.amazon.com/eks">Amazon Elastic Kubernetes Service (EKS)</a> and <a href="https://azure.microsoft.com/en-us/services/kubernetes-service">Azure Kubernetes Service (AKS)</a>.
@@ -26,7 +26,7 @@ These are the platform requirements to use Authorino:
 
 - [**Envoy**](https://www.envoyproxy.io) proxy (recommended v1.19 or later), to wire up Upstream services (i.e. the services to be protected with Authorino) and external authorization filter (Authorino) for integrations based on the reverse-proxy architecture - [example](https://github.com/kuadrant/authorino-examples#envoy)
 
-  <details>
+  <details markdown="1">
     <summary>Alternative: Non-reverse-proxy integration</summary>
 
     Technically, any client that implements Envoy's <a href="https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/ext_authz">external authorization</a> gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino.
@@ -66,7 +66,7 @@ Choose either [cluster-wide or namespaced deployment mode](./architecture.md#clu
 
 The instructions here are for centralized gateway or centralized authorization service architecture. Check out the [Topologies](./architecture.md#topologies) section of the docs for alternatively running Authorino in a sidecar container.
 
-<details>
+<details markdown="1">
   <summary><strong>Cluster-wide (with TLS)</strong></summary>
 
   Create the namespace:
@@ -103,7 +103,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Cluster-wide (without TLS)</strong></summary>
 
   ```sh
@@ -127,7 +127,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Namespaced (with TLS)</strong></summary>
 
   Create the namespace:
@@ -165,7 +165,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Namespaced (without TLS)</strong></summary>
 
   ```sh
diff --git a/docs/user-guides/anonymous-access.md b/docs/user-guides/anonymous-access.md
index 3325b3ea..13e54a69 100644
--- a/docs/user-guides/anonymous-access.md
+++ b/docs/user-guides/anonymous-access.md
@@ -2,7 +2,7 @@
 
 Bypass identity verification or fall back to anonymous access when credentials fail to validate
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/api-key-authentication.md b/docs/user-guides/api-key-authentication.md
index 98376f7c..fcf2d899 100644
--- a/docs/user-guides/api-key-authentication.md
+++ b/docs/user-guides/api-key-authentication.md
@@ -2,7 +2,7 @@
 
 Issue API keys stored in Kubernetes `Secret`s for clients to authenticate with your protected hosts.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md b/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md
index 5d7714a9..7d03fd5c 100644
--- a/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md
+++ b/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md
@@ -2,7 +2,7 @@
 
 Provide Envoy with dynamic metadata about the external authorization process to be injected into the rate limiting filter.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/authzed.md b/docs/user-guides/authzed.md
index dc5c3734..dc5e56ee 100644
--- a/docs/user-guides/authzed.md
+++ b/docs/user-guides/authzed.md
@@ -2,7 +2,7 @@
 
 Permission requests sent to a Google Zanzibar-based [Authzed/SpiceDB](https://authzed.com) instance, via gRPC.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/caching.md b/docs/user-guides/caching.md
index 7243ae73..c6535e46 100644
--- a/docs/user-guides/caching.md
+++ b/docs/user-guides/caching.md
@@ -15,7 +15,7 @@ Cases where one will **NOT** want to enable caching, due to relatively cheap com
 - Dynamic JSON responses
 - Anonymous access
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/deny-with-redirect-to-login.md b/docs/user-guides/deny-with-redirect-to-login.md
index 1107a833..928b5c6e 100644
--- a/docs/user-guides/deny-with-redirect-to-login.md
+++ b/docs/user-guides/deny-with-redirect-to-login.md
@@ -2,7 +2,7 @@
 
 Customize response status code and headers on failed requests to redirect users of a web application protected with Authorino to a login page instead of a `401 Unauthorized`.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md
index fefcef71..95ae37c3 100644
--- a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md
+++ b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md
@@ -10,7 +10,7 @@ The very definition of "edge" is subject to discussion, but the underlying idea
 
 As a minimum, EAA allows to simplify authentication between applications and microservices inside the network, as well as to reduce authorization to domain-specific rules and policies, rather than having to deal all the complexity to support all types of clients in every node.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/envoy-jwt-authn-and-authorino.md b/docs/user-guides/envoy-jwt-authn-and-authorino.md
index c8eb764d..640f3537 100644
--- a/docs/user-guides/envoy-jwt-authn-and-authorino.md
+++ b/docs/user-guides/envoy-jwt-authn-and-authorino.md
@@ -8,7 +8,7 @@ The policy defines a geo-fence by which only requests originated in Great Britai
 
 All requests to the Talker API will be authenticated in Envoy. However, requests to `/global` will **not** trigger the external authorization.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/external-metadata.md b/docs/user-guides/external-metadata.md
index b11b7b7b..3635f269 100644
--- a/docs/user-guides/external-metadata.md
+++ b/docs/user-guides/external-metadata.md
@@ -2,7 +2,7 @@
 
 Get online data from remote HTTP services to enhance authorization rules.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/http-basic-authentication.md b/docs/user-guides/http-basic-authentication.md
index c5a7aca4..15296fc9 100644
--- a/docs/user-guides/http-basic-authentication.md
+++ b/docs/user-guides/http-basic-authentication.md
@@ -2,7 +2,7 @@
 
 Turn Authorino API key `Secret`s settings into HTTP basic auth.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/injecting-data.md b/docs/user-guides/injecting-data.md
index 421e1cbe..63e1a8f4 100644
--- a/docs/user-guides/injecting-data.md
+++ b/docs/user-guides/injecting-data.md
@@ -2,7 +2,7 @@
 
 Inject HTTP headers with serialized JSON content.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/json-pattern-matching-authorization.md b/docs/user-guides/json-pattern-matching-authorization.md
index 7b0c9ea1..90dcfe6e 100644
--- a/docs/user-guides/json-pattern-matching-authorization.md
+++ b/docs/user-guides/json-pattern-matching-authorization.md
@@ -2,7 +2,7 @@
 
 Write simple authorization rules based on JSON patterns matched against Authorino's Authorization JSON; check contextual information of the request, validate JWT claims, cross metadata fetched from external sources, etc.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/keycloak-authorization-services.md b/docs/user-guides/keycloak-authorization-services.md
index 663c89b1..231494e6 100644
--- a/docs/user-guides/keycloak-authorization-services.md
+++ b/docs/user-guides/keycloak-authorization-services.md
@@ -4,7 +4,7 @@ Keycloak provides a powerful set of tools (REST endpoints and administrative UIs
 
 This user guide is an example of how to use Authorino as an adapter to Keycloak Authorization Services while still relying on the reverse-proxy integration pattern, thus not involving importing an authorization library nor rebuilding the application's code.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/kubernetes-subjectaccessreview.md b/docs/user-guides/kubernetes-subjectaccessreview.md
index 1283a272..43fd36c9 100644
--- a/docs/user-guides/kubernetes-subjectaccessreview.md
+++ b/docs/user-guides/kubernetes-subjectaccessreview.md
@@ -2,7 +2,7 @@
 
 Manage permissions in the Kubernetes RBAC and let Authorino to check them in request-time with the authorization system of the cluster.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
@@ -309,7 +309,7 @@ kubectl run speaker --attach --rm --restart=Never -q --image=quay.io/kuadrant/au
 # 403
 ```
 
-<details>
+<details markdown="1">
   <summary>Extra: consume the API as service account <code>api-consumer-2</code> from <i>outside</i> the cluster</summary>
 
   <br/>
diff --git a/docs/user-guides/kubernetes-tokenreview.md b/docs/user-guides/kubernetes-tokenreview.md
index 718d80a1..a70caa9f 100644
--- a/docs/user-guides/kubernetes-tokenreview.md
+++ b/docs/user-guides/kubernetes-tokenreview.md
@@ -2,7 +2,7 @@
 
 Validate Kubernetes Service Account tokens to authenticate requests to your protected hosts.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/mtls-authentication.md b/docs/user-guides/mtls-authentication.md
index 64df235a..c43b4879 100644
--- a/docs/user-guides/mtls-authentication.md
+++ b/docs/user-guides/mtls-authentication.md
@@ -2,7 +2,7 @@
 
 Verify client X.509 certificates against trusted root CAs stored in Kubernetes `Secret`s to authenticate access to APIs protected with Authorino.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/oauth2-token-introspection.md b/docs/user-guides/oauth2-token-introspection.md
index 2f39ef10..4980a0c0 100644
--- a/docs/user-guides/oauth2-token-introspection.md
+++ b/docs/user-guides/oauth2-token-introspection.md
@@ -2,7 +2,7 @@
 
 Introspect OAuth 2.0 access tokens (e.g. opaque tokens) for online user data and token validation in request-time.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/observability.md b/docs/user-guides/observability.md
index 94837b10..ba845b45 100644
--- a/docs/user-guides/observability.md
+++ b/docs/user-guides/observability.md
@@ -232,7 +232,7 @@ The [Authorino Operator](https://github.com/kuadrant/authorino-operator) creates
 
 <sup>2</sup> Opt-in metrics: <code>auth_server_evaluator_*</code> metrics require <code>authconfig.spec.(identity|metadata|authorization|response).metrics: true</code> (default: <code>false</code>). This can be enforced for the entire instance (all AuthConfigs and evaluators), by setting the <code>--deep-metrics-enabled</code> command-line flag in the Authorino deployment.
 
-<details>
+<details markdown="1">
   <summary><b>Example of metrics exported at the <code>/metrics</code> endpoint</b></summary>
 
   ```ini
@@ -651,7 +651,7 @@ The [Authorino Operator](https://github.com/kuadrant/authorino-operator) creates
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><b>Example of metrics exported at the <code>/server-metrics</code> endpoint</b></summary>
 
   ```ini
@@ -1233,7 +1233,7 @@ Some log messages printed by Authorino and corresponding extra values included:
 
 The examples below are all with `--log-level=debug` and `--log-mode=production`.
 
-<details>
+<details markdown="1">
   <summary>Booting up the service</summary>
 
   ```jsonc
@@ -1260,7 +1260,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary>Reconciling an AuthConfig and 2 related API key secrets</summary>
 
   ```jsonc
@@ -1282,7 +1282,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary>Enforcing an AuthConfig with authentication based on Kubernetes tokens:</summary>
 
   <br/>
@@ -1316,7 +1316,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary>Enforcing an AuthConfig with authentication based on API keys</summary>
 
   <br/>
@@ -1349,7 +1349,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary>Enforcing an AuthConfig with authentication based on API keys (invalid API key)</summary>
 
   <br/>
@@ -1371,7 +1371,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary>Deleting an AuthConfig and 2 related API key secrets</summary>
 
 
@@ -1382,7 +1382,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`.
 </details>
 
 
-<details>
+<details markdown="1">
   <summary>Shutting down the service</summary>
 
   ```jsonc
diff --git a/docs/user-guides/oidc-jwt-authentication.md b/docs/user-guides/oidc-jwt-authentication.md
index 5f59518f..62bd3255 100644
--- a/docs/user-guides/oidc-jwt-authentication.md
+++ b/docs/user-guides/oidc-jwt-authentication.md
@@ -2,7 +2,7 @@
 
 Validate JSON Web Tokens (JWT) issued and signed by an OpenID Connect server; leverage OpenID Connect Discovery to automatically fetch JSON Web Key Sets (JWKS).
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/oidc-rbac.md b/docs/user-guides/oidc-rbac.md
index d7adac32..29a54357 100644
--- a/docs/user-guides/oidc-rbac.md
+++ b/docs/user-guides/oidc-rbac.md
@@ -4,7 +4,7 @@ Combine OpenID Connect (OIDC) authentication and Role-Based Access Control (RBAC
 
 In this user guide, you will learn via example how to implement a simple Role-Based Access Control (RBAC) system to protect endpoints of an API, with roles assigned to users of an Identity Provider (Keycloak) and carried within the access tokens as JSON Web Token (JWT) claims. Users authenticate with the IdP via OAuth2/OIDC flow and get their access tokens verified and validated by Authorino on every request. Moreover, Authorino reads the role bindings of the user and enforces the proper RBAC rules based upon the context.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/oidc-user-info.md b/docs/user-guides/oidc-user-info.md
index 04f377c8..1e1bcd8b 100644
--- a/docs/user-guides/oidc-user-info.md
+++ b/docs/user-guides/oidc-user-info.md
@@ -2,7 +2,7 @@
 
 Fetch user info for OpenID Connect ID tokens in request-time for extra metadata for your policies and online verification of token validity.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/opa-authorization.md b/docs/user-guides/opa-authorization.md
index 4b8ba847..83d66f56 100644
--- a/docs/user-guides/opa-authorization.md
+++ b/docs/user-guides/opa-authorization.md
@@ -2,7 +2,7 @@
 
 Leverage the power of Open Policy Agent (OPA) policies, evaluated against Authorino's Authorization JSON in a built-in runtime compiled together with Authorino; pre-cache policies defined in Rego language inline or fetched from an external policy registry.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/passing-credentials.md b/docs/user-guides/passing-credentials.md
index bd53cc8a..6d9afbbf 100644
--- a/docs/user-guides/passing-credentials.md
+++ b/docs/user-guides/passing-credentials.md
@@ -2,7 +2,7 @@
 
 Customize where credentials are supplied in the request by each trusted source of identity.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/resource-level-authorization-uma.md b/docs/user-guides/resource-level-authorization-uma.md
index bf6e6db4..f66f178f 100644
--- a/docs/user-guides/resource-level-authorization-uma.md
+++ b/docs/user-guides/resource-level-authorization-uma.md
@@ -2,7 +2,7 @@
 
 Fetch resource metadata relevant for your authorization policies from Keycloak authorization clients, using User-Managed Access (UMA) protocol.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/sharding.md b/docs/user-guides/sharding.md
index 73fb7cc2..647d4bfc 100644
--- a/docs/user-guides/sharding.md
+++ b/docs/user-guides/sharding.md
@@ -17,7 +17,7 @@ By default, Authorino will watch events related to all `AuthConfig` custom resou
   </tbody>
 </table>
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/token-normalization.md b/docs/user-guides/token-normalization.md
index 555ad167..472da5fd 100644
--- a/docs/user-guides/token-normalization.md
+++ b/docs/user-guides/token-normalization.md
@@ -8,7 +8,7 @@ This user guide focuses on the aspect of mutation of the identity claims resolve
 
 For not only normalizing the identity claims for purpose of writing simpler authorization checks and policies, but also getting Authorino to issue a new token in a normalized format, check the [Festival Wristband tokens](../features.md#festival-wristband-tokens-responsesuccessheadersdynamicmetadatawristband) feature.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>
diff --git a/docs/user-guides/validating-webhook.md b/docs/user-guides/validating-webhook.md
index 2bf85913..90e2e428 100644
--- a/docs/user-guides/validating-webhook.md
+++ b/docs/user-guides/validating-webhook.md
@@ -6,7 +6,7 @@ The rules to validate a request to the Kubernetes API – typically a `POST`, `P
 
 This user guide provides an example of using Authorino as a Kubernetes ValidatingWebhook service that validates requests to `CREATE` and `UPDATE` Authorino `AuthConfig` resources. In other words, we will use Authorino as a validator inside the cluster that decides what is a valid AuthConfig for any application which wants to rely on Authorino to protect itself.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>