Revamp installation how-to guides

docs/assets/scss/_code.scss

@@ -1,88 +1,110 @@
-// Code formatting.
+/* ---- Code block overrides (Chroma + Highlight.js) ---- */
 
-.highlight .copy-icon {
-    position: absolute;
-    right: 20px;
-    top: 18px;
-    opacity: 0.7;
+/* Ensure the copy icon is always visible and positioned */
+.td-content .highlight {
+  position: relative; /* anchor for absolutely positioned copy icon */
 }
 
-
-.highlight pre {
-    /* Avoid pushing up the copy buttons. */
-    margin: 0;
+/* --- Copy icon: always visible and colored --- */
+.td-content .highlight {
+  position: relative;
 }
 
-.td-content {
-
-    // Highlighted code.
-    .highlight {
-        @extend .card;
-
-        margin: 0rem 0;
-        padding: 0rem;
-
-        margin-bottom: 2rem;
-
-        max-width: 100%;
-
-        border: none;
-
-        pre {
-            margin: 0;
-            padding: 1rem;
-            border-radius: 10px;
-        }
+/* Always visible */
+.td-content .highlight .copy-icon {
+  position: absolute;
+  right: 20px;
+  top: 18px;
+  z-index: 2;
+
+  /* Always show */
+  opacity: 1 !important;
+  visibility: visible !important;
+  pointer-events: auto;
+  transition: none !important;
+
+  /* 🔹 Visual style */
+  background-color: #444;       /* primary blue, adjust as needed */
+  color: #ffffff;                  /* white icon/text */
+  border: none;
+  border-radius: 6px;
+  padding: 6px 8px;
+  font-size: 0.85rem;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  &:hover {
+    background-color: #444;     /* darker blue on hover */
+  }
+}
 
-        table td:nth-child(2) {
-            display: grid;
-            background-color: #fff;
+/* Make ALL code block surfaces light grey, regardless of renderer */
+.td-content .highlight,
+.td-content .highlight pre,
+.td-content .highlight table,
+.td-content .highlight td,
+.td-content pre,
+.td-content pre > code,
+.td-content .chroma,
+.td-content .chroma .hl,
+.td-content code[class*="language-"],
+.td-content pre[class*="language-"] {
+  background-color: #f5f5f5 !important; /* light grey */
+  color: #1a1a1a;                       /* readable text */
+  border-radius: 10px;
+}
 
-            pre {
-                border-radius: 0px 0px 0px 0px;
-            }
-        }
-    }
+/* Fix the table layout Chroma uses so the grey fills the code cell */
+.td-content .highlight table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+}
 
-    // Inline code
-    p code,
-    li>code,
-    table code {
-        color: inherit;
-        padding: 0.2em 0.4em;
-        margin: 0;
-        font-size: 85%;
-        word-break: normal;
-        background-color: rgba($black, 0.05);
-        border-radius: $border-radius;
+.td-content .highlight td {
+  border: 0;
+  padding: 0;
+}
 
-        br {
-            display: none;
-        }
-    }
+/* Keep inner <pre> edges flush when inside the table wrapper */
+.td-content .highlight table td:nth-child(2) pre {
+  border-radius: 0 0 0 0;
+  margin: 0;
+  padding: 1rem;
+}
 
+/* Override Chroma inline string/link color (yellow) for better readability */
+.td-content .highlight span[style*="#e6db74"],
+.td-content .highlight span[style*="#f1fa8c"],
+.td-content pre span[style*="#e6db74"],
+.td-content pre span[style*="#f1fa8c"] {
+  color: #1d4ed8 !important;
+}
 
-    // Code blocks
-    pre {
-        word-wrap: normal;
-        background-color: $gray-100;
-        padding: $spacer;
+/* Generic <pre> blocks outside .highlight */
+.td-content pre {
+  margin: 0;
+  padding: 1rem;
+  word-wrap: normal;
+}
 
-        max-width: 100%;
+/* Inline code stays subtle */
+.td-content p code,
+.td-content li > code,
+.td-content table code {
+  background-color: rgba(0, 0, 0, 0.05);
+}
 
-        >code {
-            background-color: inherit !important;
-            padding: 0;
-            margin: 0;
-            font-size: 100%;
-            word-break: normal;
-            white-space: pre;
-            border: 0;
-        }
-    }
+/* Override string color (yellow) in code blocks */
+.td-content .highlight .chroma .s,
+.td-content .highlight .chroma .s1,
+.td-content .highlight .chroma .s2 {
+  color: #0a66c2 !important;  /* example: Azure blue */
+}
 
-    pre.mermaid {
-        background-color: inherit;
-        font-size: 0;
-    }
+/* Or neutralize syntax coloring for a more uniform look */
+.td-content .highlight .chroma * {
+  color: #1a1a1a !important;
 }

docs/config.toml

@@ -5,6 +5,8 @@ theme =  "docsy"
 
 disableFastRender = true
 
+googleAnalytics = "G-9JR8B6TPF9"
+
 # Ignore sample code
 ignoreFiles = ["/code/*"]
 
@@ -95,6 +97,12 @@ version_menu = "Releases"
   [markup.goldmark]
     [markup.goldmark.renderer]
       unsafe = true
+[markup.highlight]
+  codeFences = true
+  guessSyntax = true
+  noClasses = true # Use inline styles instead of CSS classes (false for CSS classes)
+  style = "github" 
+  tabWidth = 4
 
 # UI Customization
 [params.ui]
@@ -109,3 +117,4 @@ navbar_logo = true
 enable = true
 yes = '<b>Glad to hear it!</b> Please feel free to <a href="https://github.com/radius-project/radius">star our repo</a> and join our <a href="https://aka.ms/radius/discord">Discord server</a> to stay up to date with the project.'
 no = '<b>Sorry to hear that.</b> If you would like to also contribute a suggestion visit <a href="https://github.com/radius-project/docs/issues/new/choose"> and tell us how we can improve</a>.'
+

docs/content/guides/author-apps/_index.md

@@ -3,5 +3,5 @@ type: docs
 title: "Authoring applications"
 linkTitle: "Authoring applications"
 description: "Learn how to author a Radius Application"
-weight: 100
+weight: 200
 ---

docs/content/guides/author-apps/aws/howto-aws-resources/index.md

@@ -58,8 +58,6 @@ Select 'No' when asked to setup application in the current directory.
 
 {{< read file= "/shared-content/installation/bicepconfig/manual.md" >}}
 
-More information on how to setup a `bicepconfig.json` can be found [here]({{< ref "/guides/tooling/bicepconfig/overview" >}})
-
 ## Step 4: Create a Bicep file to model AWS Simple Storage Service (S3)
 
 Create a new file called `app.bicep` and add the following bicep code to model an AWS S3 Bucket:

docs/content/guides/author-apps/azure/howto-azure-container-instances/index.md

@@ -17,8 +17,8 @@ This how-to guide will provide an overview of how to:
 ## Prerequisites
 
 - [rad CLI]({{< ref "installation#step-1-install-the-rad-cli" >}})
-The [Bicep extension]({{< ref "installation#step-2-install-the-vs-code-extension" >}}) for VS Code is recommended for Bicep language support
-- Radius [installed]({{< ref "/guides/operations/kubernetes/kubernetes-install" >}}) on a [supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-kubernetes-clusters" >}})
+- The [Bicep extension]({{< ref "installation#step-2-install-the-vs-code-extension" >}}) for VS Code is recommended for Bicep language support
+- Radius [installed]({{< ref "/guides/installation" >}}) on a [supported Kubernetes cluster]({{< ref "/guides/installation/#kubernetes-requirements" >}})
 - An Azure provider configured and registered with your Radius control plane, either through [Service Principal](https://docs.radapp.io/guides/operations/providers/azure-provider/howto-azure-provider-sp/) or [Workload Identity](https://docs.radapp.io/guides/operations/providers/azure-provider/howto-azure-provider-wi/) that have been assigned to the `Reader` role on the subscription and the `Contributor` role on the resource group where the ACI containers will be deployed
 - A [managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/) is [required]({{< ref "/reference/resource-schema/core-schema/environment-schema#identity" >}}) for ACI deployments, if you choose to utilize a [user-assigned managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp) then you need to ensure it is assigned to the `Contributor` and `Azure Container Instances Contributor` roles on the subscription and resource group where the ACI containers will be deployed
 
@@ -201,4 +201,4 @@ Navigate to the Todo List tab and test out the application. Using the Todo page
 - [Azure resources overview]({{< ref "/guides/author-apps/azure/overview" >}})
 - [Radius Environment schema]({{< ref "/reference/resource-schema/core-schema/environment-schema" >}})
 - [Radius Application schema]({{< ref "/reference/resource-schema/core-schema/application-schema" >}})
-- [Radius Container schema]({{< ref "/reference/resource-schema/core-schema/container-schema" >}})
+- [Radius Container schema]({{< ref "/reference/resource-schema/core-schema/container-schema" >}})

docs/content/guides/author-apps/azure/howto-azure-resources/index.md

@@ -38,8 +38,6 @@ Select 'No' when asked to setup application in the current directory.
 
 {{< read file= "/shared-content/installation/bicepconfig/manual.md" >}}
 
-More information on how to setup a `bicepconfig.json` can be found [here]({{< ref "/guides/tooling/bicepconfig/overview" >}})
-
 ## Step 3: Define a Radius Environment
 
 Create a file named `app.bicep` and define a [Radius Environment]({{< ref "concepts/environments" >}}) with identity property set. This configures your environment to use your Azure AD workload identity installation with your cluster's OIDC endpoint:

docs/content/guides/author-apps/containers/howto-keyvault-volume/index.md

@@ -39,8 +39,6 @@ Select 'No' when asked to setup application in the current directory.
 
 {{< read file= "/shared-content/installation/bicepconfig/manual.md" >}}
 
-More information on how to setup a `bicepconfig.json` can be found [here]({{< ref "/guides/tooling/bicepconfig/overview" >}})
-
 ## Step 3: Define a Radius Environment
 
 Create a file named `app.bicep` and define a Radius Environment with the identity property set:

docs/content/guides/deploy-apps/environments/howto-environment/index.md

@@ -25,7 +25,7 @@ Radius Environments can be setup with the rad CLI via two paths: interactive or
    rad init
    ```
 
-   Select `Yes` to setup the application in the current directory. This will create `app.bicep` and [`bicepconfig.json`]({{< ref "/guides/tooling/bicepconfig/overview" >}}) files
+   Select `Yes` to setup the application in the current directory. This will create `app.bicep` and `bicepconfig.json`
 
    ```
    Initializing Radius...

docs/content/guides/deploy-apps/howto-deploy/howto-deploy-cicd/index.md

@@ -13,7 +13,7 @@ It's easy to get Radius added to your GitHub Actions deployment pipelines. By le
 ## Prerequisites
 
 - [Setup a supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}})
-- Radius control plane [installed in your cluster]({{< ref kubernetes-install >}})
+- [Radius installed in your cluster]({{< ref "/guides/installation/install" >}})
 - GitHub repo with Actions enabled
 
 ## Step 1: Create your environment and application definitions
@@ -28,7 +28,7 @@ Make sure you have the following files checked into your repository under `iac/`
 
 {{< rad file="snippets/app.bicep" embed="true" >}}
 
-### [`bicepconfig.json`]({{< ref "/guides/tooling/bicepconfig/overview" >}})
+### `bicepconfig.json`
 
 ```json
 {