Overview

This PR enhances the remarkFileCodeBlock plugin to support absolute paths using the <root>/ prefix, in addition to the existing relative path support.

Motivation

Previously, users could only reference files using relative paths (./ or ../), which made it challenging to maintain consistent imports across different documentation locations. When reorganizing docs or referencing files from deeply nested MDX files, users had to use complex relative paths like ../../../src/components/Button.tsx.

Changes

1. Enhanced Path Resolution

The plugin now supports three path formats:

• ./file.tsx - Relative to current file (existing)
• ../file.tsx - Relative to parent directory (existing)
• <root>/path/to/file.tsx - Absolute from document root (new)

2. Implementation

Modified fileCodeBlock.ts:

• Added docDirectory parameter to plugin signature
• Implemented path resolution logic for <root>/ prefix:

  if (file.startsWith('<root>/')) {
    resolvedFilePath = path.join(docDirectory, file.slice('<root>/'.length));
  }

• Updated error messages to document the new syntax

Updated options.ts:

• Passed docDirectory parameter to the plugin

3. Usage Example

Before:

```tsx file="../../../src/components/Button.tsx"
```

After:

```tsx file="<root>/src/components/Button.tsx"
```

Both syntaxes continue to work, providing flexibility for different use cases.

Benefits

• Consistency: Same path works from any MDX file location
• Maintainability: Easier to reorganize documentation structure without updating all paths
• Clarity: Absolute paths are more explicit than complex relative paths
• Backward Compatible: All existing relative paths continue to work

Testing

Added comprehensive test coverage including:

• ✅ Basic absolute path resolution
• ✅ Nested absolute paths
• ✅ Error handling for non-existent files
• ✅ Error handling for non-empty content blocks

All existing tests continue to pass, ensuring no breaking changes.

Closes #ISSUE_NUMBER

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.