From b3dbaebd274001ff3c21220a1568352ed549d875 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Breu=C3=9F?= <vbreuss@gmail.com>
Date: Wed, 6 May 2026 18:08:19 +0200
Subject: [PATCH] fix: broken link to Extensions

---
 .gitignore                           |  2 +-
 Docs/mirror-local-docs.ps1           | 10 ++++++----
 Docs/pages/docs/Extensions/index.mdx | 21 +++++++++++++++++++++
 Pipeline/Build.Pages.cs              |  7 +++++--
 4 files changed, 33 insertions(+), 7 deletions(-)
 create mode 100644 Docs/pages/docs/Extensions/index.mdx

diff --git a/.gitignore b/.gitignore
index a6a1c95e..f42b3902 100644
--- a/.gitignore
+++ b/.gitignore
@@ -408,5 +408,5 @@ Docs/pages/build/
 Docs/pages/docs/Abstractions
 Docs/pages/docs/aweXpect
 Docs/pages/docs/Mockolate
-Docs/pages/docs/Extensions
+Docs/pages/docs/Extensions/*/
 Docs/pages/docs/Chronology
diff --git a/Docs/mirror-local-docs.ps1 b/Docs/mirror-local-docs.ps1
index 21e30502..9cb03e12 100644
--- a/Docs/mirror-local-docs.ps1
+++ b/Docs/mirror-local-docs.ps1
@@ -100,12 +100,11 @@ function Ensure-SidebarPosition([string]$content, [int]$position) {
     return "---`nsidebar_position: $position`n---`n`n$content"
 }
 
-if (Test-Path -LiteralPath $DocsRoot) {
-    Write-Host "Cleaning $DocsRoot"
-    Remove-Item -LiteralPath $DocsRoot -Recurse -Force
-}
 New-Item -ItemType Directory -Path $DocsRoot -Force | Out-Null
 
+# Clean each target subdirectory rather than the whole DocsRoot so that
+# site-owned overlays committed under docs/ (e.g. Extensions/index.mdx)
+# survive the mirror.
 foreach ($source in $Sources) {
     $sourceDir = Join-Path $Root (Join-Path $source.Repo $source.SourcePath)
     $targetDir = Join-Path $DocsRoot $source.Target
@@ -118,6 +117,9 @@ foreach ($source in $Sources) {
         continue
     }
 
+    if (Test-Path -LiteralPath $targetDir) {
+        Remove-Item -LiteralPath $targetDir -Recurse -Force
+    }
     New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
 
     $readmeIntro = ""
diff --git a/Docs/pages/docs/Extensions/index.mdx b/Docs/pages/docs/Extensions/index.mdx
new file mode 100644
index 00000000..ab5917ef
--- /dev/null
+++ b/Docs/pages/docs/Extensions/index.mdx
@@ -0,0 +1,21 @@
+---
+title: Extensions
+sidebar_position: 0
+---
+
+# Extensions
+
+Add-on packages that extend the core Testably libraries with focused
+expectations and integrations for popular ecosystems.
+
+## aweXpect extensions
+
+- **[aweXpect.Json](./aweXpect.Json/)** — expectations for `System.Text.Json`.
+- **[aweXpect.Web](./aweXpect.Web/)** — expectations for `HttpClient` and
+  `HttpResponseMessage`.
+- **[aweXpect.Reflection](./aweXpect.Reflection/)** — expectations for
+  reflection types.
+- **[aweXpect.Testably](./aweXpect.Testably/)** — expectations for
+  Testably.Abstractions file and time systems.
+- **[aweXpect.Mockolate](./aweXpect.Mockolate/)** — expectations for
+  Mockolate mock interactions.
\ No newline at end of file
diff --git a/Pipeline/Build.Pages.cs b/Pipeline/Build.Pages.cs
index 52e65f34..f87a540e 100644
--- a/Pipeline/Build.Pages.cs
+++ b/Pipeline/Build.Pages.cs
@@ -88,14 +88,17 @@ record ReadmeSubstitution(
 		.Executes(async () =>
 		{
 			AbsolutePath docsRoot = RootDirectory / "Docs" / "pages" / "docs";
-			docsRoot.CreateOrCleanDirectory();
+			docsRoot.CreateDirectory();
 
+			// Clean each target subdirectory rather than the whole docsRoot so that
+			// site-owned overlays committed under docs/ (e.g. Extensions/index.mdx)
+			// survive the build.
 			foreach (DocsSource source in AggregatedSources)
 			{
 				AbsolutePath targetDirectory = string.IsNullOrEmpty(source.TargetSubDirectory)
 					? docsRoot
 					: docsRoot / source.TargetSubDirectory;
-				targetDirectory.CreateDirectory();
+				targetDirectory.CreateOrCleanDirectory();
 				await DownloadDocsContent(source, targetDirectory);
 			}
 		});