Link Patterns (Fork)
Note: This is a fork of dlevs/vscode-pattern-links with additional features and improvements.
Link Patterns is a VS Code extension that automatically turns text into links based upon regex patterns.
Installation
You can install this extension in several ways:
VS Code Marketplace: Search for TobiasHochguertel.pattern-links-fork
Command Line:
code --install-extension TobiasHochguertel.pattern-links-fork
VSIX File:
code --install-extension pattern-links-fork-1.1.0.vsix
Configuration
Multiple patterns can be defined in your VS Code settings. The following examples highlight common use cases.
{
"patternlinks.rules": [
{
"linkPattern": "ISSUE-\\d+",
"linkTarget": "https://myorg.atlassian.net/browse/$0"
// Example URL: https://myorg.atlassian.net/browse/ISSUE-299
},
{
"linkPattern": "(FOO|BAR)-(\\d+)",
"linkTarget": "https://example.com/$1/$2",
// Example URL: https://example.com/FOO/123
// Limit to specific languages
"languages": ["plaintext", "markdown"]
},
{
"linkPattern": "SKU([A-Z_]+)",
"linkTarget": "https://shop.com?search=$1&min-price=\\$1"
// Example URL: https://shop.com?search=PRODUCT_CODE&min-price=$1
// Here, `\` is being used as an escape character to prevent substitution
// of the second `$1`.
}
]
}
Rule precedence
When two rules apply to the same text, the one defined last wins.
{
"patternlinks.rules": [
// Match links like repo-name#22 to the relevant pull request
{
"linkPattern": "([a-z_-]+)#(\\d+)",
"linkPatternFlags": "i", // Case insensitive
"linkTarget": "https://github.com/myorg/$1/pull/$2"
},
// Match links like special-case#22 to the relevant pull request,
// which is in a different github organization, and has a long,
// inconvenient name.
{
"linkPattern": "special-case#(\\d+)",
"linkTarget": "https://github.com/someorg/really-long-inconvenient-name/pull/$1"
}
]
}
The text special-case#22
technically matches both of these rules, but the second one is the one that takes effect.
File URL Examples
You can create clickable links to local files using various patterns. Here are some examples:
Basic File Links
This rule converts absolute file:// URLs into clickable links:
{
"patternlinks.rules": [
{
"linkPattern": "file://(/[^ \\n]+)",
"linkTarget": "file://$1",
"description": "Convert absolute file:// URLs to clickable links",
// Example: file:///path/to/file.txt -> clicks open /path/to/file.txt
"languages": ["plaintext", "markdown", "typescript", "javascript"]
}
]
}
This rule makes @document tags in comments clickable:
{
"patternlinks.rules": [
{
"linkPattern": "@document (.*?)(?=\\s|$)",
"linkTarget": "file://$1",
"description": "Make @document tags in comments clickable",
// Example: @document ../api.md -> clicks open ../api.md
"languages": ["typescript", "javascript", "java"]
}
]
}
Example usage in code:
/**
* Some documentation
* @document ../../../../external-repositories/docs/api.md
*/
Relative Path Links
This rule makes relative file paths clickable:
{
"patternlinks.rules": [
{
"linkPattern": "file://(\\.[^ \\n]+)",
"linkTarget": "file://$1",
"description": "Make relative file paths clickable",
// Example: file://./docs/README.md -> clicks open ./docs/README.md
"languages": ["plaintext", "markdown", "typescript", "javascript"]
}
]
}
Example usage:
// See documentation at file://./docs/README.md
// Or parent directory: file://../other-project/README.md
Note: The extension properly handles spaces in file paths, automatically encoding them as %20
in the URL.
File URL Handling
The extension provides special handling for file://
URLs to ensure proper path resolution and encoding:
Absolute Paths: When using absolute paths (starting with /
), special characters like spaces are automatically encoded:
file:///path/with spaces/file.txt → file:///path/with%20spaces/file.txt
Relative Paths: When using relative paths (starting with .
or ..
), the path structure is preserved:
file://./relative/path.txt → file://./relative/path.txt
file://../parent/path.txt → file://../parent/path.txt
Other URIs: Non-file URLs (e.g., http://
) are handled normally.
This ensures that both absolute and relative file paths work correctly, while maintaining proper URL encoding for special characters.
Debugging Links
The extension provides debug mode and file logging to help troubleshoot link matching and generation.
Debug Mode
To enable debugging:
- Open the Command Palette (
Cmd+Shift+P
on macOS, Ctrl+Shift+P
on Windows/Linux)
- Run the command
Pattern Links: Toggle Debug Mode
When debug mode is enabled:
- Hovering over a link will show detailed information about:
- The matched text
- The rule that was applied
- The generated URI
- Debug logs will be written to the Output panel (View > Output, select "Pattern Links" from the dropdown)
- Links will still be clickable and function normally
File Logging
For persistent debugging, you can enable file logging:
- Open the Command Palette (
Cmd+Shift+P
on macOS, Ctrl+Shift+P
on Windows/Linux)
- Run the command
Pattern Links: Toggle File Logging
When file logging is enabled:
- Debug messages will be written to a log file in addition to the Output panel
- The log file location will be shown in the Output panel when file logging is enabled
- Log messages include timestamps and are deduplicated to prevent redundant entries
- Each log entry contains detailed information about link creation and pattern matching
- During test mode, logging is automatically disabled to prevent interference with test results
Configuration options for logging can be set in your VS Code settings:
{
"patternlinks.debug": {
"maxQueueSize": 1000, // Maximum number of messages to queue before processing
"enabled": false, // Enable/disable debug mode
"fileLogging": false // Enable/disable file logging
}
}
Debug mode and file logging are particularly useful when:
- Your regex patterns aren't matching as expected
- The generated URIs aren't what you expect
- You want to understand which rule is being applied to a specific match
- You need to track pattern matching behavior over time
Contributing
- Clone this repository
npm install
to install dependencies
npm run watch
to start the compiler in watch mode
- Open this folder in VS Code and start the debugger (
F5
).
Publishing
This extension is available on both the VS Code Marketplace and Open VSX Registry:
Publishing Process
To publish a new version:
Update the version in package.json
Create and push a new tag:
git tag v1.x.x # Replace with your version
git push origin v1.x.x
The GitHub Actions workflow will automatically:
- Build and test the extension
- Publish to VS Code Marketplace
- Publish to Open VSX Registry
- Create a GitHub release with the .vsix file
Manual Publishing
You can also publish manually using the provided npm scripts:
# Publish to VS Code Marketplace
pnpm run publish:vscode
# Publish to Open VSX Registry
pnpm run publish:ovsx
# Publish to both marketplaces
pnpm run publish:all
Note: You'll need to set up the following tokens: