@larkiny/astro-github-loader 0.11.0 → 0.11.2

package/dist/github.link-transform.js

@@ -35,17 +35,15 @@ function isExternalLink(link) {
  */
 function normalizePath(linkPath, currentFilePath, logger) {
     logger?.debug(`[normalizePath] BEFORE: linkPath="${linkPath}", currentFilePath="${currentFilePath}"`);
-    // Handle relative paths
-    if (linkPath.startsWith('./') || linkPath.includes('../')) {
+    // Handle relative paths (including simple relative paths without ./ prefix)
+    // A link is relative if it doesn't start with / or contain a protocol
+    const isAbsoluteOrExternal = linkPath.startsWith('/') || linkPath.includes('://') || linkPath.startsWith('#');
+    if (!isAbsoluteOrExternal) {
         const currentDir = path.dirname(currentFilePath);
         const resolved = path.posix.normalize(path.posix.join(currentDir, linkPath));
         logger?.debug(`[normalizePath] RELATIVE PATH RESOLVED: "${linkPath}" -> "${resolved}" (currentDir: "${currentDir}")`);
         return resolved;
     }
-    // Remove leading './'
-    if (linkPath.startsWith('./')) {
-        return linkPath.slice(2);
-    }
     logger?.debug(`[normalizePath] AFTER: "${linkPath}" (no changes)`);
     return linkPath;
 }
@@ -188,7 +186,11 @@ function transformLink(linkText, linkUrl, context) {
         }
     }
     // Check if this links to an imported file
-    const targetPath = context.global.sourceToTargetMap.get(normalizedPath);
+    let targetPath = context.global.sourceToTargetMap.get(normalizedPath);
+    // If not found and path ends with /, try looking for index.md
+    if (!targetPath && normalizedPath.endsWith('/')) {
+        targetPath = context.global.sourceToTargetMap.get(normalizedPath + 'index.md');
+    }
     if (targetPath) {
         // This is an internal link to an imported file
         const siteUrl = generateSiteUrl(targetPath, context.global.stripPrefixes);
@@ -214,8 +216,10 @@ function transformLink(linkText, linkUrl, context) {
             }
         }
     }
-    // No transformation needed - return processed URL
-    return `[${linkText}](${processedNormalizedPath + anchor})`;
+    // No transformation matched - strip .md extension from unresolved internal links
+    // This handles links to files that weren't imported but should still use Starlight routing
+    const cleanPath = processedNormalizedPath.replace(/\.md$/i, '');
+    return `[${linkText}](${cleanPath + anchor})`;
 }
 /**
  * Global link transformation function

package/dist/github.link-transform.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/github.link-transform.spec.js

@@ -0,0 +1,222 @@
+import { describe, it, expect } from 'vitest';
+import { globalLinkTransform } from './github.link-transform.js';
+describe('globalLinkTransform', () => {
+    describe('relative link resolution', () => {
+        it('should resolve simple relative links without ./ prefix', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/front-end-guide/index.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/overview.md',
+                    content: '[Designing a language](02-designing-a-language.md)',
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/02-designing-a-language.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/02-designing-a-language.md',
+                    content: '# Designing a language',
+                    id: 'file2',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Designing a language](/reference/api/front-end-guide/02-designing-a-language/)');
+        });
+        it('should resolve relative links with ./ prefix', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/front-end-guide/index.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/overview.md',
+                    content: '[Intro](./00-introduction.md)',
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/00-introduction.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/00-introduction.md',
+                    content: '# Introduction',
+                    id: 'file2',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Intro](/reference/api/front-end-guide/00-introduction/)');
+        });
+        it('should resolve relative links with ../ prefix', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/front-end-guide/subfolder/page.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/subfolder/page.md',
+                    content: '[Back to overview](../index.md)',
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/index.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/overview.md',
+                    content: '# Overview',
+                    id: 'file2',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Back to overview](/reference/api/front-end-guide/overview/)');
+        });
+        it('should preserve absolute links', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/page.md',
+                    targetPath: 'src/content/docs/page.md',
+                    content: '[Absolute link](/some/absolute/path)',
+                    id: 'file1',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Absolute link](/some/absolute/path)');
+        });
+        it('should preserve external links', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/page.md',
+                    targetPath: 'src/content/docs/page.md',
+                    content: '[External](https://example.com)',
+                    id: 'file1',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[External](https://example.com)');
+        });
+        it('should preserve anchor-only links', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/page.md',
+                    targetPath: 'src/content/docs/page.md',
+                    content: '[Jump to section](#my-section)',
+                    id: 'file1',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Jump to section](#my-section)');
+        });
+        it('should preserve anchors in relative links', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/front-end-guide/index.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/overview.md',
+                    content: '[Section](02-designing-a-language.md#primitive-types)',
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/02-designing-a-language.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/02-designing-a-language.md',
+                    content: '# Designing a language',
+                    id: 'file2',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe('[Section](/reference/api/front-end-guide/02-designing-a-language/#primitive-types)');
+        });
+        it('should handle multiple links in the same file', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/front-end-guide/index.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/overview.md',
+                    content: `
+[Introduction](00-introduction.md)
+[Calling puya](01-calling-puya.md)
+[Designing a language](02-designing-a-language.md)
+          `.trim(),
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/00-introduction.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/00-introduction.md',
+                    content: '# Introduction',
+                    id: 'file2',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/01-calling-puya.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/01-calling-puya.md',
+                    content: '# Calling Puya',
+                    id: 'file3',
+                },
+                {
+                    sourcePath: 'docs/front-end-guide/02-designing-a-language.md',
+                    targetPath: 'src/content/docs/reference/api/front-end-guide/02-designing-a-language.md',
+                    content: '# Designing a language',
+                    id: 'file4',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            expect(result[0].content).toBe(`
+[Introduction](/reference/api/front-end-guide/00-introduction/)
+[Calling puya](/reference/api/front-end-guide/01-calling-puya/)
+[Designing a language](/reference/api/front-end-guide/02-designing-a-language/)
+      `.trim());
+        });
+        it('should strip .md extension from unresolved relative links', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/page.md',
+                    targetPath: 'src/content/docs/page.md',
+                    content: '[Unresolved](some-file-not-in-map.md)',
+                    id: 'file1',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [],
+            });
+            // Should normalize to docs/some-file-not-in-map (current file's dir + relative link)
+            // but not resolve to full path since file not in map, so just strips .md
+            expect(result[0].content).toBe('[Unresolved](docs/some-file-not-in-map)');
+        });
+    });
+    describe('index.md handling', () => {
+        it('should convert index.md to trailing slash', () => {
+            const files = [
+                {
+                    sourcePath: 'docs/page.md',
+                    targetPath: 'src/content/docs/page.md',
+                    content: '[Link](subfolder/index.md)',
+                    id: 'file1',
+                },
+                {
+                    sourcePath: 'docs/subfolder/index.md',
+                    targetPath: 'src/content/docs/subfolder/index.md',
+                    content: '# Index',
+                    id: 'file2',
+                },
+            ];
+            const result = globalLinkTransform(files, {
+                stripPrefixes: ['src/content/docs'],
+                linkMappings: [
+                    {
+                        pattern: /\/index$/,
+                        replacement: '/',
+                        global: true,
+                    },
+                ],
+            });
+            expect(result[0].content).toBe('[Link](/subfolder/)');
+        });
+    });
+});

package/package.json

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

package/src/content/docs/algokit/cli/accounts.md

@@ -0,0 +1 @@
+# Content

package/src/content/docs/algokit/cli/generate.md

@@ -0,0 +1 @@
+# Content

package/src/content/docs/algokit/cli/overview.md

@@ -0,0 +1 @@
+# Content

package/src/content/docs/algokit/cli/tasks.md

@@ -0,0 +1 @@
+# Content

package/src/content/docs/reference/algokit-cli/index.md

@@ -0,0 +1 @@
+# Content

package/src/github.link-transform.ts

@@ -104,19 +104,17 @@ function isExternalLink(link: string): boolean {
 function normalizePath(linkPath: string, currentFilePath: string, logger?: Logger): string {
   logger?.debug(`[normalizePath] BEFORE: linkPath="${linkPath}", currentFilePath="${currentFilePath}"`);
 
-  // Handle relative paths
-  if (linkPath.startsWith('./') || linkPath.includes('../')) {
+  // Handle relative paths (including simple relative paths without ./ prefix)
+  // A link is relative if it doesn't start with / or contain a protocol
+  const isAbsoluteOrExternal = linkPath.startsWith('/') || linkPath.includes('://') || linkPath.startsWith('#');
+
+  if (!isAbsoluteOrExternal) {
     const currentDir = path.dirname(currentFilePath);
     const resolved = path.posix.normalize(path.posix.join(currentDir, linkPath));
     logger?.debug(`[normalizePath] RELATIVE PATH RESOLVED: "${linkPath}" -> "${resolved}" (currentDir: "${currentDir}")`);
     return resolved;
   }
 
-  // Remove leading './'
-  if (linkPath.startsWith('./')) {
-    return linkPath.slice(2);
-  }
-
   logger?.debug(`[normalizePath] AFTER: "${linkPath}" (no changes)`);
   return linkPath;
 }
@@ -286,7 +284,12 @@ function transformLink(linkText: string, linkUrl: string, context: LinkContext):
   }
 
   // Check if this links to an imported file
-  const targetPath = context.global.sourceToTargetMap.get(normalizedPath);
+  let targetPath = context.global.sourceToTargetMap.get(normalizedPath);
+
+  // If not found and path ends with /, try looking for index.md
+  if (!targetPath && normalizedPath.endsWith('/')) {
+    targetPath = context.global.sourceToTargetMap.get(normalizedPath + 'index.md');
+  }
 
   if (targetPath) {
     // This is an internal link to an imported file
@@ -316,8 +319,10 @@ function transformLink(linkText: string, linkUrl: string, context: LinkContext):
     }
   }
 
-  // No transformation needed - return processed URL
-  return `[${linkText}](${processedNormalizedPath + anchor})`;
+  // No transformation matched - strip .md extension from unresolved internal links
+  // This handles links to files that weren't imported but should still use Starlight routing
+  const cleanPath = processedNormalizedPath.replace(/\.md$/i, '');
+  return `[${linkText}](${cleanPath + anchor})`;
 }
 
 /**