@larkiny/astro-github-loader 0.14.0 → 0.14.2

package/dist/github.content.js

@@ -304,9 +304,11 @@ export async function toCollectionEntry({ context, octokit, options, signal, for
     let processedFiles = allFiles;
     if (options.linkTransform) {
         logger.verbose(`Applying link transformation to ${allFiles.length} files`);
+        // Resolve stripPrefixes with Starlight default
+        const stripPrefixes = options.linkTransform.stripPrefixes ?? ['src/content/docs'];
         // Generate automatic link mappings from pathMappings
         const autoGeneratedMappings = options.includes
-            ? generateAutoLinkMappings(options.includes, options.linkTransform.stripPrefixes)
+            ? generateAutoLinkMappings(options.includes, stripPrefixes)
             : [];
         // Combine auto-generated mappings with user-defined mappings
         const allLinkMappings = [
@@ -315,7 +317,7 @@ export async function toCollectionEntry({ context, octokit, options, signal, for
         ];
         logger.debug(`Generated ${autoGeneratedMappings.length} automatic link mappings from pathMappings`);
         processedFiles = globalLinkTransform(allFiles, {
-            stripPrefixes: options.linkTransform.stripPrefixes,
+            stripPrefixes,
             customHandlers: options.linkTransform.customHandlers,
             linkMappings: allLinkMappings,
             logger,

package/dist/github.link-transform.js

@@ -181,6 +181,19 @@ function transformLink(linkText, linkUrl, context) {
         return `[${linkText}](${linkUrl})`;
     }
     const { path: linkPath, anchor } = extractAnchor(linkUrl);
+    // Try global linkMappings on the RAW link path before normalization.
+    // Bare-path links (e.g., "docs/markdown/autoapi/foo/") are repo-root-relative
+    // but normalizePath() treats them as file-relative, mangling the path.
+    // Applying global mappings first lets patterns match the link as written.
+    if (context.global.linkMappings) {
+        const globalMappings = context.global.linkMappings.filter((m) => m.global);
+        if (globalMappings.length > 0) {
+            const rawMapped = applyLinkMappings(linkPath + anchor, globalMappings, context);
+            if (rawMapped !== linkPath + anchor) {
+                return `[${linkText}](${rawMapped})`;
+            }
+        }
+    }
     // Normalize the link path relative to current file FIRST
     const normalizedPath = normalizePath(linkPath, context.currentFile.sourcePath, context.global.logger);
     // Apply global path mappings to the normalized path

package/dist/github.types.d.ts

@@ -38,8 +38,8 @@ export interface LinkMapping {
  * Configuration for import link transformation
  */
 export interface ImportLinkTransformOptions {
-    /** Base paths to strip from final URLs (e.g., ["src/content/docs"]) */
-    stripPrefixes: string[];
+    /** Base paths to strip from final URLs. Defaults to ["src/content/docs"] (Starlight convention). */
+    stripPrefixes?: string[];
     /** Custom handlers for special link types */
     customHandlers?: LinkHandler[];
     /** Link mappings to transform URLs in markdown links */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@larkiny/astro-github-loader",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Load content from GitHub repositories into Astro content collections with asset management and content transformations",
   "keywords": [
     "astro",

package/src/github.content.ts

@@ -434,12 +434,12 @@ export async function toCollectionEntry({
   if (options.linkTransform) {
     logger.verbose(`Applying link transformation to ${allFiles.length} files`);
 
+    // Resolve stripPrefixes with Starlight default
+    const stripPrefixes = options.linkTransform.stripPrefixes ?? ['src/content/docs'];
+
     // Generate automatic link mappings from pathMappings
     const autoGeneratedMappings = options.includes
-      ? generateAutoLinkMappings(
-          options.includes,
-          options.linkTransform.stripPrefixes,
-        )
+      ? generateAutoLinkMappings(options.includes, stripPrefixes)
       : [];
 
     // Combine auto-generated mappings with user-defined mappings
@@ -453,7 +453,7 @@ export async function toCollectionEntry({
     );
 
     processedFiles = globalLinkTransform(allFiles, {
-      stripPrefixes: options.linkTransform.stripPrefixes,
+      stripPrefixes,
       customHandlers: options.linkTransform.customHandlers,
       linkMappings: allLinkMappings,
       logger,

package/src/github.link-transform.spec.ts

@@ -120,6 +120,32 @@ describe("globalLinkTransform", () => {
       expect(result[0].content).toBe("[See other](/other/)");
     });
 
+    it("should apply global linkMappings to bare-path links before normalization", () => {
+      const files: ImportedFile[] = [
+        createImportedFile(
+          "docs/markdown/capabilities/guide.md",
+          "src/content/docs/guide.md",
+          "[`AccountManager`](docs/markdown/autoapi/algokit_utils/accounts/account_manager/#algokit_utils.accounts.account_manager.AccountManager)",
+        ),
+      ];
+
+      const result = globalLinkTransform(files, {
+        stripPrefixes: ["src/content/docs"],
+        linkMappings: [
+          {
+            pattern: /^docs\/markdown\/autoapi\/algokit_utils\/(.+)/,
+            replacement: "/docs/algokit-utils/python/latest/api/$1",
+            global: true,
+          },
+        ],
+        logger,
+      });
+
+      expect(result[0].content).toBe(
+        "[`AccountManager`](/docs/algokit-utils/python/latest/api/accounts/account_manager/#algokit_utils.accounts.account_manager.AccountManager)",
+      );
+    });
+
     it("should preserve anchors in transformed links", () => {
       const files: ImportedFile[] = [
         createImportedFile(

package/src/github.link-transform.ts

@@ -314,6 +314,24 @@ function transformLink(
 
   const { path: linkPath, anchor } = extractAnchor(linkUrl);
 
+  // Try global linkMappings on the RAW link path before normalization.
+  // Bare-path links (e.g., "docs/markdown/autoapi/foo/") are repo-root-relative
+  // but normalizePath() treats them as file-relative, mangling the path.
+  // Applying global mappings first lets patterns match the link as written.
+  if (context.global.linkMappings) {
+    const globalMappings = context.global.linkMappings.filter((m) => m.global);
+    if (globalMappings.length > 0) {
+      const rawMapped = applyLinkMappings(
+        linkPath + anchor,
+        globalMappings,
+        context,
+      );
+      if (rawMapped !== linkPath + anchor) {
+        return `[${linkText}](${rawMapped})`;
+      }
+    }
+  }
+
   // Normalize the link path relative to current file FIRST
   const normalizedPath = normalizePath(
     linkPath,

package/src/github.types.ts

@@ -52,8 +52,8 @@ export interface LinkMapping {
  * Configuration for import link transformation
  */
 export interface ImportLinkTransformOptions {
-  /** Base paths to strip from final URLs (e.g., ["src/content/docs"]) */
-  stripPrefixes: string[];
+  /** Base paths to strip from final URLs. Defaults to ["src/content/docs"] (Starlight convention). */
+  stripPrefixes?: string[];
   /** Custom handlers for special link types */
   customHandlers?: LinkHandler[];
   /** Link mappings to transform URLs in markdown links */