Fix relative link handling an use standard transforms for community pages (#103)

Author: petecheslock

remote-content/README.md

@@ -387,6 +387,53 @@ Different repositories may have different link structures or conventions. The `r
 - Adjusting image paths
 - Handling repository-specific markdown formats
 
+#### Link Transformation Behavior
+
+The system automatically transforms relative links in markdown files to ensure they work correctly in the documentation site:
+
+**Relative Links → GitHub URLs**
+- Links without `./` prefix (e.g., `[file.md](file.md)` or `[PR_SIGNOFF.md](PR_SIGNOFF.md)`)
+- Links with `./` prefix (e.g., `[file.md](./file.md)`)
+- Links with `../` navigation (e.g., `[file.md](../../other/file.md)`)
+- All are transformed to absolute GitHub URLs: `https://github.com/org/repo/blob/main/path/file.md`
+
+**Internal Guide Links → Local Docs**
+- Specific guide files listed in `INTERNAL_GUIDE_MAPPINGS` (in `repo-transforms.js`)
+- These stay within the docs site for better navigation
+- Example: `guides/QUICKSTART.md` → `/docs/guide/Installation/quickstart`
+
+**Images → GitHub Raw URLs**
+- All relative image paths are converted to GitHub raw URLs
+- Example: `![image](./image.png)` → `![image](https://github.com/org/repo/raw/main/path/image.png)`
+
+**Using `createStandardTransform()`**
+
+All content sources should use `createStandardTransform()` to get consistent link handling:
+
+```javascript
+const contentTransform = createStandardTransform('llm-d');
+
+// Then pass it to createContentWithSource:
+createContentWithSource({
+  // ... other options
+  contentTransform  // Apply standard transformations
+})
+```
+
+For special cases where you need to override specific links after transformation:
+
+```javascript
+const contentTransform = (content, sourcePath) => {
+  const standardTransform = createStandardTransform('llm-d');
+  const transformed = standardTransform(content, sourcePath);
+  
+  // Override specific GitHub links to stay local
+  return transformed
+    .replace(/\(https:\/\/github\.com\/llm-d\/llm-d\/blob\/main\/CODE_OF_CONDUCT\.md\)/g, '(code-of-conduct)')
+    .replace(/\(https:\/\/github\.com\/llm-d\/llm-d\/blob\/main\/SIGS\.md\)/g, '(sigs)');
+};
+```
+
 ## 📁 File Structure
 
 ```
@@ -468,14 +515,16 @@ For non-component content:
 | Page not appearing | Check source URL is publicly accessible |
 | Build errors | Verify all `YOUR-...` placeholders are replaced |
 | Wrong sidebar order | Check `sidebarPosition` numbers |
-| Links broken | Use `contentTransform` to fix relative links or add to `repo-transforms.js` |
+| Links broken | Ensure you're using `createStandardTransform()` - it automatically fixes relative links to GitHub URLs |
+| Relative links not working | All relative links (with or without `./`) are automatically converted to GitHub URLs by `createStandardTransform()` |
 | Import errors | Ensure file is imported in `remote-content/remote-content.js` with correct path |
 | Component not showing | Check `component-configs.js` and ensure repository is public |
 | Source banner missing | Verify you're using `createContentWithSource()` from utils.js |
 | Banner at wrong location | Source banners now appear at bottom of pages automatically |
 | Import path errors | Use `../` to reference utils from subdirectories (e.g., `../utils.js`) |
 | File in wrong directory | Move to appropriate subdirectory: `architecture/`, `guide/`, or `community/` |
 | Template not working | Ensure you're using the updated template with correct import paths |
+| Need local links | Override specific links after `createStandardTransform()` - see "Using `createStandardTransform()`" section above |
 
 ## 📝 Content Source Banners
 

remote-content/remote-sources/community/code-of-conduct.js

@@ -5,12 +5,13 @@
  * and transforms it into docs/community/code-of-conduct.md
  */
 
-import { createContentWithSource } from '../utils.js';
+import { createContentWithSource, createStandardTransform } from '../utils.js';
 import { findRepoConfig, generateRepoUrls } from '../component-configs.js';
 
 // Get repository configuration from centralized config
 const repoConfig = findRepoConfig('llm-d');
 const { repoUrl, sourceBaseUrl } = generateRepoUrls(repoConfig);
+const contentTransform = createStandardTransform('llm-d');
 
 export default [
   'docusaurus-plugin-remote-content',
@@ -37,7 +38,8 @@ export default [
           newFilename: 'code-of-conduct.md',
           repoUrl,
           branch: repoConfig.branch,
-          content
+          content,
+          contentTransform
         });
       }
       return undefined;

remote-content/remote-sources/community/contribute.js

@@ -5,13 +5,23 @@
  * and transforms it into docs/community/contribute.md
  */
 
-import { createContentWithSource } from '../utils.js';
+import { createContentWithSource, createStandardTransform } from '../utils.js';
 import { findRepoConfig, generateRepoUrls } from '../component-configs.js';
 
 // Get repository configuration from centralized config
 const repoConfig = findRepoConfig('llm-d');
 const { repoUrl, sourceBaseUrl } = generateRepoUrls(repoConfig);
 
+// Create content transform that applies standard transformations,
+// then overrides specific links that should stay local to the docs site
+const contentTransform = (content, sourcePath) => {
+  const standardTransform = createStandardTransform('llm-d');
+  const transformed = standardTransform(content, sourcePath);
+  return transformed
+    .replace(/\(https:\/\/github\.com\/llm-d\/llm-d\/blob\/main\/CODE_OF_CONDUCT\.md\)/g, '(code-of-conduct)')
+    .replace(/\(https:\/\/github\.com\/llm-d\/llm-d\/blob\/main\/SIGS\.md\)/g, '(sigs)');
+};
+
 export default [
   'docusaurus-plugin-remote-content',
   {
@@ -38,10 +48,7 @@ export default [
           repoUrl,
           branch: repoConfig.branch,
           content,
-          // Fix relative links in the content
-          contentTransform: (content) => content
-            .replace(/\(CODE_OF_CONDUCT\.md\)/g, '(code-of-conduct)')
-            .replace(/\(SIGS\.md\)/g, '(sigs)')
+          contentTransform
         });
       }
       return undefined;

remote-content/remote-sources/community/security.js

@@ -5,12 +5,13 @@
  * and transforms it into docs/community/security.md
  */
 
-import { createContentWithSource } from '../utils.js';
+import { createContentWithSource, createStandardTransform } from '../utils.js';
 import { findRepoConfig, generateRepoUrls } from '../component-configs.js';
 
 // Get repository configuration from centralized config
 const repoConfig = findRepoConfig('llm-d');
 const { repoUrl, sourceBaseUrl } = generateRepoUrls(repoConfig);
+const contentTransform = createStandardTransform('llm-d');
 
 export default [
   'docusaurus-plugin-remote-content',
@@ -38,8 +39,7 @@ export default [
           repoUrl,
           branch: repoConfig.branch,
           content,
-          // No additional content transformations needed for SECURITY.md
-          contentTransform: (content) => content
+          contentTransform
         });
       }
       return undefined;