From 825ea7409d09ac32ce021df79965a9c6fc5b4331 Mon Sep 17 00:00:00 2001
From: Larkin Young <larkin.young@algorand.foundation>
Date: Mon, 16 Feb 2026 23:09:14 +0000
Subject: [PATCH] Require absolute path from bare-path global linkMapping early
 return

The early return for bare-path global linkMappings now requires the
mapped result to start with "/" (absolute path). This prevents generic
global mappings like .md-stripping from hijacking multi-segment relative
links (e.g., "types/subscription.md") that should resolve via
normalizePath() + sourceToTargetMap.

Bumps version to 0.14.5.
---
 package-lock.json                             |  2 +-
 packages/astro-github-loader/package.json     |  2 +-
 .../src/github.link-transform.spec.ts         | 33 +++++++++++++++++++
 .../src/github.link-transform.ts              |  2 +-
 4 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 9413bca..1af2a06 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10053,7 +10053,7 @@
     },
     "packages/astro-github-loader": {
       "name": "@larkiny/astro-github-loader",
-      "version": "0.11.3",
+      "version": "0.14.1",
       "license": "MIT",
       "dependencies": {
         "@octokit/auth-app": "^8.1.1",
diff --git a/packages/astro-github-loader/package.json b/packages/astro-github-loader/package.json
index e683c63..c82287e 100644
--- a/packages/astro-github-loader/package.json
+++ b/packages/astro-github-loader/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@larkiny/astro-github-loader",
   "type": "module",
-  "version": "0.14.4",
+  "version": "0.14.5",
   "description": "Load content from GitHub repositories into Astro content collections with asset management and content transformations",
   "keywords": [
     "astro",
diff --git a/packages/astro-github-loader/src/github.link-transform.spec.ts b/packages/astro-github-loader/src/github.link-transform.spec.ts
index e374c7f..52052d7 100644
--- a/packages/astro-github-loader/src/github.link-transform.spec.ts
+++ b/packages/astro-github-loader/src/github.link-transform.spec.ts
@@ -244,6 +244,39 @@ describe("globalLinkTransform", () => {
       expect(result[0].content).toBe("[See B](/api/page-b/#section)");
     });
 
+    it("should not early-return multi-segment bare-path sibling references with .md", () => {
+      // Multi-segment bare paths like "types/subscription.md" are file-relative
+      // sibling references (e.g., from subscriber.md to types/subscription.md).
+      // The .md-stripping global mapping should NOT cause an early return — the
+      // link must flow through normalizePath() + sourceToTargetMap to resolve.
+      const files: ImportedFile[] = [
+        createImportedFile(
+          "latest/api/subscriber.md",
+          "src/content/docs/docs/algokit-subscriber/typescript/latest/api/subscriber.md",
+          "[`AlgorandSubscriberConfig`](types/subscription.md#algorandsubscriberconfig)",
+        ),
+        createImportedFile(
+          "latest/api/types/subscription.md",
+          "src/content/docs/docs/algokit-subscriber/typescript/latest/api/types/subscription.md",
+          "# subscription",
+        ),
+      ];
+
+      const result = globalLinkTransform(files, {
+        stripPrefixes: ["src/content/docs"],
+        linkMappings: [
+          { pattern: /\.md(#|$)/, replacement: "$1", global: true },
+          { pattern: /\/index(\.md)?$/, replacement: "/", global: true },
+        ],
+        logger,
+      });
+
+      // Should resolve via sourceToTargetMap to absolute URL, NOT leave as relative
+      expect(result[0].content).toBe(
+        "[`AlgorandSubscriberConfig`](/docs/algokit-subscriber/typescript/latest/api/types/subscription/#algorandsubscriberconfig)",
+      );
+    });
+
     it("should preserve anchors in transformed links", () => {
       const files: ImportedFile[] = [
         createImportedFile(
diff --git a/packages/astro-github-loader/src/github.link-transform.ts b/packages/astro-github-loader/src/github.link-transform.ts
index 2905391..309e569 100644
--- a/packages/astro-github-loader/src/github.link-transform.ts
+++ b/packages/astro-github-loader/src/github.link-transform.ts
@@ -337,7 +337,7 @@ function transformLink(
         globalMappings,
         context,
       );
-      if (rawMapped !== linkPath + anchor) {
+      if (rawMapped !== linkPath + anchor && rawMapped.startsWith("/")) {
         return `[${linkText}](${rawMapped})`;
       }
     }