Kuadrant · Boomatang · Nov 22, 2023 · Nov 10, 2023 · Nov 20, 2023 · Nov 10, 2023
diff --git a/README.md b/README.md
@@ -7,27 +7,6 @@
 
 The Operator to install and manage the lifecycle of the [Kuadrant](https://github.com/Kuadrant/) components deployments.
 
-<!--ts-->
-- [Overview](#overview)
-- [Architecture](#architecture)
-  - [Kuadrant components](#kuadrant-components)
-  - [Provided APIs](#provided-apis)
-- [Getting started](#getting-started)
-  - [Pre-requisites](#pre-requisites)
-  - [Installing Kuadrant](#installing-kuadrant)
-    - [1. Install the Kuadrant Operator](#1-install-the-kuadrant-operator)
-    - [2. Request a Kuadrant instance](#2-request-a-kuadrant-instance)
-  - [Protect your service](#protect-your-service)
-    - [If you are an *API Provider*](#if-you-are-an-api-provider)
-    - [If you are a *Cluster Operator*](#if-you-are-a-cluster-operator)
-- [User guides](#user-guides)
-- [Kuadrant Rate Limiting](#kuadrant-rate-limiting)
-- [Documentation](#documentation)
-- [Contributing](#contributing)
-- [Licensing](#licensing)
-
-<!--te-->
-
 ## Overview
 
 Kuadrant is a re-architecture of API Management using Cloud Native concepts and separating the components to be less coupled,
@@ -75,7 +54,7 @@ Additionally, Kuadrant provides the following CRDs
 |--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
 | [Kuadrant CRD](https://github.com/Kuadrant/kuadrant-operator/blob/main/api/v1beta1/kuadrant_types.go)        | [Kuadrant Operator](https://github.com/Kuadrant/kuadrant-operator)   | Represents an instance of kuadrant  | [Kuadrant CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/config/samples/kuadrant_v1beta1_kuadrant.yaml)              |
 | [Limitador CRD](https://github.com/Kuadrant/limitador-operator/blob/main/api/v1alpha1/limitador_types.go)    | [Limitador Operator](https://github.com/Kuadrant/limitador-operator) | Represents an instance of Limitador | [Limitador CR](https://github.com/Kuadrant/limitador-operator/blob/main/config/samples/limitador_v1alpha1_limitador.yaml)         |
-| [Authorino CRD](https://github.com/Kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) |
+| [Authorino CRD](https://docs.kuadrant.io/authorino-operator/#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) |
 
 <img alt="Kuadrant Architecture" src="doc/images/kuadrant-architecture.svg" />
 

diff --git a/doc/development.md b/doc/development.md
@@ -1,26 +1,5 @@
 # Development Guide
 
-<!--ts-->
-   * [Technology stack required for development](#technology-stack-required-for-development)
-   * [Build](#build)
-   * [Run locally](#run-locally)
-   * [Deploy the operator in a deployment object](#deploy-the-operator-in-a-deployment-object)
-   * [Deploy kuadrant operator using OLM](#deploy-kuadrant-operator-using-olm)
-   * [Build custom OLM catalog](#build-custom-olm-catalog)
-      * [Build kuadrant operator bundle image](#build-kuadrant-operator-bundle-image)
-      * [Build custom catalog](#build-custom-catalog)
-   * [Cleaning up](#cleaning-up)
-   * [Run tests](#run-tests)
-      * [Unit tests](#unittests)
-      * [Integration tests](#integration-tests)
-      * [All tests](#all-tests)
-      * [Lint tests](#lint-tests)
-   * [(Un)Install Kuadrant CRDs](#uninstall-kuadrant-crds)
-
-<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
-
-<!--te-->
-
 ## Technology stack required for development
 
 * [operator-sdk] version v1.28.1

diff --git a/doc/user-guides/authenticated-rl-for-app-developers.md b/doc/user-guides/authenticated-rl-for-app-developers.md
@@ -2,15 +2,12 @@
 
 This user guide walks you through an example of how to configure authenticated rate limiting for an application using Kuadrant.
 
-<br/>
-
 Authenticated rate limiting rate limits the traffic directed to an application based on attributes of the client user, who is authenticated by some authentication method. A few examples of authenticated rate limiting use cases are:
+
 - User A can send up to 50rps ("requests per second"), while User B can send up to 100rps.
 - Each user can send up to 20rpm ("request per minute").
 - Admin users (members of the 'admin' group) can send up to 100rps, while regular users (non-admins) can send up to 20rpm and no more than 5rps.
 
-<br/>
-
 In this guide, we will rate limit a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request. The API exposes an endpoint at `GET http://api.toystore.com/toy`, to mimic an operation of reading toy records.
 
 We will define 2 users of the API, which can send requests to the API at different rates, based on their user IDs. The authentication method used is **API key**.
@@ -20,8 +17,6 @@ We will define 2 users of the API, which can send requests to the API at differe
 | alice   | 5rp10s ("5 requests every 10 seconds") |
 | bob     | 2rp10s ("2 requests every 10 seconds") |
 
-<br/>
-
 ## Run the steps ① → ④
 
 ### ① Setup
@@ -225,8 +220,6 @@ EOF
 
 > **Note:** It may take a couple of minutes for the RateLimitPolicy to be applied depending on your cluster.
 
-<br/>
-
 Verify the rate limiting works by sending requests as Alice and Bob.
 
 Up to 5 successful (`200 OK`) requests every 10 seconds allowed for Alice, then `429 Too Many Requests`:

diff --git a/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md b/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md
@@ -1,13 +1,12 @@
 # Authenticated Rate Limiting with JWTs and Kubernetes RBAC
 
 This user guide walks you through an example of how to use Kuadrant to protect an application with policies to enforce:
+
 - authentication based OpenId Connect (OIDC) ID tokens (signed JWTs), issued by a Keycloak server;
 - alternative authentication method by Kubernetes Service Account tokens;
 - authorization delegated to Kubernetes RBAC system;
 - rate limiting by user ID.
 
-<br/>
-
 In this example, we will protect a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request.
 
 The API listens to requests at the hostnames `*.toystore.com`, where it exposes the endpoints `GET /toy*`, `POST /admin/toy` and `DELETE /amind/toy`, respectively, to mimic operations of reading, creating, and deleting toy records.
@@ -266,14 +265,14 @@ subjects:
 EOF
 ```
 
-<details>
+<details markdown="1">
   <summary><i>Q:</i> Can I use <code>Roles</code> and <code>RoleBindings</code> instead of <code>ClusterRoles</code> and <code>ClusterRoleBindings</code>?</summary>
 
   Yes, you can.
 
   The example above is for non-resource URL Kubernetes roles. For using `Roles` and `RoleBindings` instead of
   `ClusterRoles` and `ClusterRoleBindings`, thus more flexible resource-based permissions to protect the API,
-  see the spec for [Kubernetes SubjectAccessReview authorization](https://github.com/Kuadrant/authorino/blob/v0.5.0/docs/features.md#kubernetes-subjectaccessreview-authorizationkubernetes)
+  see the spec for [Kubernetes SubjectAccessReview authorization](https://docs.kuadrant.io/authorino/docs/features/#kubernetes-subjectaccessreview-authorizationkubernetessubjectaccessreview)
   in the Authorino docs.
 </details>