diff --git a/remote-content/README.md b/remote-content/README.md index 08367ca..00af42f 100644 --- a/remote-content/README.md +++ b/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,7 +515,8 @@ 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 | @@ -476,6 +524,7 @@ For non-component content: | 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 diff --git a/remote-content/remote-sources/community/code-of-conduct.js b/remote-content/remote-sources/community/code-of-conduct.js index 63c326e..98da2d2 100644 --- a/remote-content/remote-sources/community/code-of-conduct.js +++ b/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; diff --git a/remote-content/remote-sources/community/contribute.js b/remote-content/remote-sources/community/contribute.js index ed5ec85..0bfb732 100644 --- a/remote-content/remote-sources/community/contribute.js +++ b/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; diff --git a/remote-content/remote-sources/community/security.js b/remote-content/remote-sources/community/security.js index a155c5b..83fbf2f 100644 --- a/remote-content/remote-sources/community/security.js +++ b/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;