fix(docs): inject base path and convert mkdocs admonitions AB#4945

Author: kristopherjturner

docs/.vitepress/config.mts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
+  base: '/azurelocal-vm-conversion-toolkit/',
   title: "azurelocal-vm-conversion-toolkit Documentation",
   description: "Governed centrally by HCS Platform Engineering standards",
   themeConfig: {
@@ -27,3 +28,4 @@ export default defineConfig({
   }
 })
 
+

docs/gen1-vs-gen2.md

@@ -1,8 +1,8 @@
 # Gen 1 vs Gen 2: Should You Convert?
 
-!!! warning
-    **Read this before running anything.** Conversion is a destructive, one-way operation. This document is intended to help you make an informed decision — and in most cases, the right answer is **not** to convert.
-
+> [!WARNING]
+> **Read this before running anything.** Conversion is a destructive, one-way operation. This document is intended to help you make an informed decision — and in most cases, the right answer is **not** to convert.
+>
 ---
 
 ## The Short Answer
@@ -134,9 +134,9 @@ If you have decided to proceed with conversion, there are two distinct paths dep
 - Portal-based VM management is not a requirement
 - You want the simplest possible path — no Azure CLI dependencies
 
-!!! note
-    Both paths are workload-preserving. Path 1 adds one extra step (`reconnect-to-azure`) after the Gen 2 conversion — it does not require Sysprep or any identity-destructive operation.
-
+> [!NOTE]
+> Both paths are workload-preserving. Path 1 adds one extra step (`reconnect-to-azure`) after the Gen 2 conversion — it does not require Sysprep or any identity-destructive operation.
+>
 ---
 
 ## Proceed to Conversion

docs/getting-started.md

@@ -35,9 +35,9 @@ Choose **one** based on how the converted VM needs to be managed after conversio
 - You want the simplest possible path with zero Azure dependencies
 - Your cluster is a standalone Hyper-V cluster without Azure Local registration
 
-!!! note
-    **Azure Local is the primary focus of this toolkit.** Path 1 is the recommended path for Azure Local clusters. Path 2 is included for environments that need Hyper-V-only management with no Azure dependencies.
-
+> [!NOTE]
+> **Azure Local is the primary focus of this toolkit.** Path 1 is the recommended path for Azure Local clusters. Path 2 is included for environments that need Hyper-V-only management with no Azure dependencies.
+>
 ---
 
 ## Before You Start
@@ -163,9 +163,9 @@ Quick reference — run these four steps in order:
     -LogicalNetworkId "/subscriptions/.../logicalNetworks/mgmt-lnet"
 ```
 
-!!! caution
-    `az stack-hci-vm reconnect-to-azure` is a **Preview** command. Confirm it is available in your `stack-hci-vm` extension before running Step 4: `az stack-hci-vm reconnect-to-azure --help`
-
+> [!CAUTION]
+> `az stack-hci-vm reconnect-to-azure` is a **Preview** command. Confirm it is available in your `stack-hci-vm` extension before running Step 4: `az stack-hci-vm reconnect-to-azure --help`
+>
 ---
 
 ## Path 2 — Hyper-V

docs/index.md

@@ -2,18 +2,19 @@
 
 ![Azure Local VM Conversion Toolkit](assets/images/azurelocal-vm-conversion-toolkit-banner.svg)
 
-!!! warning "Under Active Development"
-    This repository is a work in progress. Scripts, templates, and automation are **not guaranteed to work** at this time. Use at your own risk and expect breaking changes.
-
+> [!WARNING]
+> **Under Active Development**
+> This repository is a work in progress. Scripts, templates, and automation are **not guaranteed to work** at this time. Use at your own risk and expect breaking changes.
+>
 Convert Gen 1 virtual machines to Gen 2 on Azure Local and Hyper-V environments.
 
 ## Overview
 
 This toolkit provides automated scripts for converting Generation 1 VMs to Generation 2, enabling UEFI boot, Secure Boot, vTPM, and Trusted Launch capabilities.
 
-!!! warning
-    Conversion is a destructive, one-way operation. Always take full backups before proceeding. Read the [Gen 1 vs Gen 2](gen1-vs-gen2.md) guide before deciding to convert.
-
+> [!WARNING]
+> Conversion is a destructive, one-way operation. Always take full backups before proceeding. Read the [Gen 1 vs Gen 2](gen1-vs-gen2.md) guide before deciding to convert.
+>
 ## Quick Navigation
 
 | Guide | Description |

docs/reference/variables.md

@@ -2,13 +2,14 @@
 
 All VM conversion scripts use a central configuration file: `config/variables.yml`. This file documents the common values you will need across all scripts. Future versions may support loading from this file directly.
 
-!!! tip "Getting started"
-    Copy the example and fill in your values:
-    ```powershell
-    cp config/variables.example.yml config/variables.yml
-    ```
-    **Never commit** `variables.yml` — it is excluded by `.gitignore` because it contains environment-specific values.
-
+> [!TIP]
+> **Getting started**
+> Copy the example and fill in your values:
+> ```powershell
+> cp config/variables.example.yml config/variables.yml
+> ```
+> **Never commit** `variables.yml` — it is excluded by `.gitignore` because it contains environment-specific values.
+>
 !!! note "Current usage"
     These scripts currently accept parameters directly on the command line.
     This file documents the common values you will need and serves as the canonical parameter reference.

docs/runbook-azurelocal.md

@@ -1,14 +1,14 @@
 # Runbook: Azure Local VM Path
 
-!!! note
-    **This runbook covers the Azure Local VM path (scripts 01–03, 05).** The resulting VM is a full `Microsoft.AzureStackHCI/virtualMachineInstances` resource visible in the Azure portal and managed through the Azure Local management plane. If you only need a Gen 2 VM managed through Hyper-V directly without portal management, see [Runbook: Hyper-V Cluster Path](runbook-hyperv.md).
-
+> [!NOTE]
+> **This runbook covers the Azure Local VM path (scripts 01–03, 05).** The resulting VM is a full `Microsoft.AzureStackHCI/virtualMachineInstances` resource visible in the Azure portal and managed through the Azure Local management plane. If you only need a Gen 2 VM managed through Hyper-V directly without portal management, see [Runbook: Hyper-V Cluster Path](runbook-hyperv.md).
+>
 !!! note
     **This path IS workload-preserving.** The VM keeps its machine identity, domain join, installed applications, and all OS state. No Sysprep. No reinstallation. The same converted Gen 2 VM that runs in Hyper-V is reconnected into the Azure control plane using `az stack-hci-vm reconnect-to-azure`.
 
-!!! warning
-    `az stack-hci-vm reconnect-to-azure` is currently in **Preview**. Validate this capability is available in your Azure Local version before planning production use.
-
+> [!WARNING]
+> `az stack-hci-vm reconnect-to-azure` is currently in **Preview**. Validate this capability is available in your Azure Local version before planning production use.
+>
 !!! warning
     Ensure all prerequisites are satisfied before you begin. See [Prerequisites](prerequisites.md).
 
@@ -99,9 +99,9 @@ Copy `scripts/azurelocal/02-Convert-MBRtoGPT.ps1` into the guest VM and run it:
 .\02-Convert-MBRtoGPT.ps1
 ```
 
-!!! caution
-    Shut down the VM immediately after — do **NOT** reboot. The disk is now GPT but the VM is still Gen 1. Rebooting will fail.
-
+> [!CAUTION]
+> Shut down the VM immediately after — do **NOT** reboot. The disk is now GPT but the VM is still Gen 1. Rebooting will fail.
+>
 ```powershell
 Stop-Computer -Force
 ```
@@ -114,9 +114,9 @@ If validation fails, see [mbr2gpt fails validation](troubleshooting.md#mbr2gpt-f
 
 This step is identical to the Hyper-V path. Run it from the cluster node after the guest VM is shut down.
 
-!!! note
-    This step deletes the Gen 1 VM object and creates a new Gen 2 Hyper-V VM with the same name, reattaching the existing VHDXs. The workload is preserved — only the VM configuration object is recreated. See [Runbook: Hyper-V Cluster Path — Step 3](runbook-hyperv.md#step-3-convert-gen-1-gen-2) for the full explanation of what the script does internally.
-
+> [!NOTE]
+> This step deletes the Gen 1 VM object and creates a new Gen 2 Hyper-V VM with the same name, reattaching the existing VHDXs. The workload is preserved — only the VM configuration object is recreated. See [Runbook: Hyper-V Cluster Path — Step 3](runbook-hyperv.md#step-3-convert-gen-1-gen-2) for the full explanation of what the script does internally.
+>
 ```powershell
 .\scripts\azurelocal\03-Convert-Gen1toGen2.ps1 `
     -VMName "WebServer01" `

docs/runbook-hyperv.md

@@ -1,13 +1,13 @@
 # Runbook: Hyper-V Cluster Path
 
-!!! note
-    **This runbook covers the Hyper-V Cluster path (scripts 01–04).** It converts a Gen 1 VM into a Gen 2 Hyper-V VM on the same cluster node. The resulting VM is managed directly through Hyper-V and does not appear as an `Microsoft.AzureStackHCI/virtualMachineInstances` resource in the Azure portal. If you need a portal-managed Azure Local VM, see [Runbook: Azure Local VM Path](runbook-azurelocal.md).
-
+> [!NOTE]
+> **This runbook covers the Hyper-V Cluster path (scripts 01–04).** It converts a Gen 1 VM into a Gen 2 Hyper-V VM on the same cluster node. The resulting VM is managed directly through Hyper-V and does not appear as an `Microsoft.AzureStackHCI/virtualMachineInstances` resource in the Azure portal. If you need a portal-managed Azure Local VM, see [Runbook: Azure Local VM Path](runbook-azurelocal.md).
+>
 This guide walks through running the Azure Local VM Conversion Toolkit from start to finish.
 
-!!! warning
-    Ensure all prerequisites are satisfied before you begin. See [Prerequisites](prerequisites.md).
-
+> [!WARNING]
+> Ensure all prerequisites are satisfied before you begin. See [Prerequisites](prerequisites.md).
+>
 ---
 
 ## Workflow Overview
@@ -76,9 +76,9 @@ Copy `scripts/hyperv/02-Convert-MBRtoGPT.ps1` into the guest VM and run it:
 .\02-Convert-MBRtoGPT.ps1
 ```
 
-!!! caution
-    Shut down the VM immediately after — do **NOT** reboot. The disk is now GPT but the VM is still Gen 1. Rebooting will fail.
-
+> [!CAUTION]
+> Shut down the VM immediately after — do **NOT** reboot. The disk is now GPT but the VM is still Gen 1. Rebooting will fail.
+>
 ```powershell
 Stop-Computer -Force
 ```
@@ -91,9 +91,9 @@ If validation fails, check `C:\Windows\setupact.log` inside the guest. See [mbr2
 
 Run from the cluster node after the guest VM is shut down.
 
-!!! note
-    This step **deletes** the Gen 1 Hyper-V VM object entirely and creates a brand new Gen 2 VM object in its place. The existing VHDX disk files are preserved and reattached — your workload data is not touched — but the VM configuration itself is destroyed and rebuilt. This is why a VHDX backup is taken first and why this operation is irreversible without that backup.
-
+> [!NOTE]
+> This step **deletes** the Gen 1 Hyper-V VM object entirely and creates a brand new Gen 2 VM object in its place. The existing VHDX disk files are preserved and reattached — your workload data is not touched — but the VM configuration itself is destroyed and rebuilt. This is why a VHDX backup is taken first and why this operation is irreversible without that backup.
+>
 Specifically, the script:
 
 1. Captures all settings (CPU, memory, NIC, VLAN, disk paths) from the Gen 1 VM

docs/troubleshooting.md

@@ -63,9 +63,9 @@ Get-Content C:\Windows\setupact.log | Select-String -Pattern "MBR2GPT" -Context
 
 **Symptom:** After Gen 2 conversion and VM boot, the VM doesn't appear in the Azure portal within 10 minutes.
 
-!!! note
-    **This section applies to Path 1 (Azure Local) only.** On Path 1, VM Arc projection is performed explicitly by running `05-Reconnect-AzureLocalVM.ps1` — it does not happen automatically after `03-Convert-Gen1toGen2.ps1`. If script 05 fails or the VM does not appear in the portal, use the steps below. Path 2 (Hyper-V) has no Azure integration — this section does not apply.
-
+> [!NOTE]
+> **This section applies to Path 1 (Azure Local) only.** On Path 1, VM Arc projection is performed explicitly by running `05-Reconnect-AzureLocalVM.ps1` — it does not happen automatically after `03-Convert-Gen1toGen2.ps1`. If script 05 fails or the VM does not appear in the portal, use the steps below. Path 2 (Hyper-V) has no Azure integration — this section does not apply.
+>
 !!! important
     On Azure Local, VM Arc enrollment is managed entirely by the **platform** — specifically the Azure Arc resource bridge and the VM Config Agent running on the host node. There is no in-guest Connected Machine agent to re-register. You cannot re-register Arc from inside the guest VM.
 
@@ -88,9 +88,9 @@ Get-EventLog -LogName Application -Source "Microsoft-AzureStack-HCI-GuestAgent"
 
 **Step 4:** Use the manual fallback command logged by `03-Convert-Gen1toGen2.ps1` at the end of its run. It logs a full `az stack-hci-vm create` command you can re-run to re-project the VM resource into Azure.
 
-!!! note
-    This fallback applies to **Path 1 (Azure Local)** only. Re-running `05-Reconnect-AzureLocalVM.ps1` directly is generally preferred over this manual fallback command.
-
+> [!NOTE]
+> This fallback applies to **Path 1 (Azure Local)** only. Re-running `05-Reconnect-AzureLocalVM.ps1` directly is generally preferred over this manual fallback command.
+>
 **Step 5:** If the VM still doesn't appear after 15 minutes with the resource bridge healthy, delete the stale Arc VM resource from Azure (if one exists) and re-run `05-Reconnect-AzureLocalVM.ps1` (**Path 1**, preferred) or re-run the `az stack-hci-vm create` fallback command logged by script 03 (**Path 1**, manual fallback). Both options apply to **Path 1 (Azure Local)** only.
 
 ---