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:

1. VS Code Marketplace: Search for TobiasHochguertel.pattern-links-fork

2. Command Line:

   code --install-extension TobiasHochguertel.pattern-links-fork
   

3. 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"]
    }
  ]
}

JSDoc @document Tags

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:

1. 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
   

2. 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
   

3. 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:

1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
2. 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:

1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
2. 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

1. Clone this repository
2. npm install to install dependencies
3. npm run watch to start the compiler in watch mode
4. 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:

• VS Code Marketplace
• Open VSX Registry

Publishing Process

To publish a new version:

1. Update the version in package.json

2. 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:

• VSCODE_MARKETPLACE_TOKEN: Get from Visual Studio Marketplace
• OVSX_TOKEN: Get from Open VSX Registry