Markdown Folder Links

A VSCode extension that makes local folder and file paths clickable in Markdown files. Click to open folders in Finder (macOS), Explorer (Windows), or your default file manager (Linux).

Features

• 🔗 Clickable folder/file links in Markdown files
• 📁 Multiple protocols for different actions:
  • folder:// - Opens the folder/file in your system's file manager
  • reveal:// - Reveals the folder/file in the file manager (shows in parent directory)
  • edit:// - Opens the path in VSCode, creating files if needed
  • view:// - Opens files in read-only mode (VSCode for text, system viewer for PDFs/images)
• 📝 Wiki-style links - Use [[folder:path]], [[reveal:path]], [[edit:path]], or [[view:path]]
• 🏠 Path expansion - Supports ~ for home directory and relative paths
• 👁️ Hover preview - See if paths exist and get file/folder information
• ⚠️ Smart handling - Prompts to create missing folders and creates files for edit:// links
• 🖥️ Cross-platform - Works on macOS, Windows, and Linux

Usage

Markdown Link Syntax

Standard markdown link format:

[Open Documents](folder://~/Documents)
[Reveal in Finder](reveal://~/Downloads/file.pdf)
[Edit in VSCode](edit://~/Projects/my-project)
[View PDF](view://~/Documents/report.pdf)

Wiki-style double brackets:

[[folder:~/Documents]]
[[reveal:~/Downloads/file.pdf]]
[[edit:~/Projects/my-app]]
[[view:~/Documents/report.pdf]]

Path Formats

• Absolute paths: /Users/username/Documents
• Home directory: ~/Documents
• Relative paths: ./subfolder or ../parent-folder
• URL encoded: Spaces and special characters are automatically handled

Protocol Comparison

Protocol	Creates Files	Opens In	Use Case
edit://	✅ Yes	VSCode (editable)	Editing files, creating new files
view://	❌ No	VSCode (preview) or system viewer	Read-only viewing, PDFs, images
folder://	N/A	File manager	Browsing folders
reveal://	N/A	File manager (highlighted)	Locating specific files

When to use view:// vs edit://:

• Use view:// for read-only content like PDFs, images, or when you want to preview without editing
• Use edit:// when you want to modify files or create them if they don't exist
• Binary files (PDF, PNG, etc.) opened with view:// use your system's default viewer

Examples

# My Project Notes

## Resources

- [Project Assets](folder://~/Projects/MyApp/assets)
- [Documentation](reveal://./docs)
- [Open Workspace in VSCode](edit://~/workspace)
- [Edit config file](edit://~/Projects/config.json)
- [View presentation](view://~/Documents/slides.pdf)
- [View diagram](view://./assets/architecture.png)

## Quick Links

- [[folder:~/Downloads]]
- [[reveal:~/Desktop/important.pdf]]
- [[edit:~/Projects/my-app]]
- [[view:~/Documents/report.pdf]]

Configuration

Access settings through VSCode Settings > Extensions > Markdown Folder Links:

• markdownFolderLinks.enableHoverPreview: Show folder path preview on hover (default: true)
• markdownFolderLinks.defaultAction: Default action for folder:// links - "open" or "reveal" (default: "open")

Installation

From VSIX file

1. Download the .vsix file
2. Open VSCode
3. Go to Extensions view (⌘+Shift+X / Ctrl+Shift+X)
4. Click "..." menu > "Install from VSIX..."
5. Select the downloaded file

From Source

1. Clone the repository
2. Run npm install
3. Run npm run compile
4. Press F5 to test in a new VSCode window

Building from Source

# Clone repository
git clone https://github.com/YOUR_USERNAME/markdown-folder-links.git
cd markdown-folder-links

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package extension
npm install -g vsce
vsce package

Running Tests

Automated tests run inside a VS Code Extension Host and verify activation, link provider behavior, and hover responses.

# Install dependencies
npm install

# Compile and run tests (first run downloads a VS Code build)
npm test

Platform-Specific Behavior

macOS

• folder:// - Opens in Finder
• reveal:// - Reveals in Finder with item selected

Windows

• folder:// - Opens in Explorer
• reveal:// - Opens Explorer with item selected

Linux

• Uses xdg-open to open with default file manager
• Supports most common desktop environments

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Author

Created with VSCode extension development best practices.

---

Note: This extension runs locally and does not send any data externally. All folder operations are performed on your local machine.