Link Map Settings

In the enhanced edition you can define link transformation for non-GitHub link processing logic by replacing the markdown link text prior to resolving the target.

Similarly, to allow completions and other plugin assisted link addresses to reflect the non-GitHub link processing for the file, you can define transformation from GitHub to non-GitHub link text.

By using scope based rendering you can customize how links are processed based on IDE defined scopes.

• Pattern Type specifies how to interpret the pattern: prefix or regex. Prefix option will cause the pattern to treated as a prefix and the replace by string will replace this prefix if matched. Regex will perform regular expression matching and replacement.
• Pattern the pattern to use for matching
• Replace by ... the replacement string to use in case of a match

For example, with pattern type set to prefix, pattern set to {{ static_root }}/ and replace by in link ref set to / will cause link addresses that start with {{ static_root }}/ to be treated as repository relative and for the project markdown files will match files in the project directory.

To allow completion to generate link addresses with the same prefix use the reverse of the pattern and replace by in link ref for pattern and replace by in link text in the second table.

Use the test sample for text and file path conversions to see if your mapping correspond to what you had in mind.

Markdown link resolution

The first table lists patterns applied to markdown link address text before trying to resolve the target file. These patterns will be searched in the the order provided and the first match will be applied.

The second table lists patterns applied to link address text before applying it to a markdown link address. This happens during completions, intentions and annotation quick fixes. These patterns will be searched in the the order provided and the first match will be applied.

Grouping Expressions

The first rule to match the text/file reference from a group of patterns will be run. The rest of the patterns in the group will be ignored.

If you have prefix rules and suffix rules you will need to put them into separate groups so that a rule from both groups will be applied to a link or a file reference.

⚠️ These text based replacements are done in the link processing engine once a link address is generated changing the original addressing format for completions, intentions, etc. For example if you create a mapping of file:/// to / then invoking an intention to change link to file: absolute format will result in the same address as repository relative addressing format, making the file: absolute format no longer available. The same applies to completions. The file: completion format will also generate repository relative addressing. Use multiple invocation of completions to cycle through available addressing formats.

Jekyll Front Matter

You can use a similar method to allow refactoring of the jekyll permalink: value when refactoring file names or any other content.

The process is similar but a caveat: the text span in the element text pattern which is replaced in the To File Reference via regex groups (numeric or named) will be replaced by the To Element Text results of the file reference replacement results when the file is renamed. For convenience and debugging your patterns, the part of the text conversion pattern that will be replaced is highlighted in the file path test result box, as shown with a light blue selection highlight in the image above.

To ignore path in the permalink (only have the file name refactored) and change the .md extension to .html use the following:

For text conversion:

• pattern regex: (?:^|\n)permalink:\s+(?:(?:.*)/)*([^\s]+)\.html(?:\s|$)
• to file reference text: $1.md

For file path conversion:

• pattern regex: (?:(?:.*)/)*([^/]+)\.md(?:\s|$)
• to file reference text: $1

Creating new Mapping Groups

Type determines which markdown elements the replacements in this group are applied:

• Link Ref Element applies to all types of elements that contain a link address: image links, explicit links and references.
• Jekyll Front Matter applies to text of a Jekyll front matter of the file
• Unused is not applied to any elements. It is useful for temporarily parking unused groups or ones with errors that prevent settings from being saved.

Initial content is provided for convenience. Available initial content depends on the element type. These "templates" for link mapping groups can be used as is or modified for your application.

• For Type Link Ref
  

  • Jekyll Link Macro: contains the patterns for converting a link starting with a jekyll macro expansion of the form {{ variable }} to a file reference where the macro is changed to a fixed path prefix.
  • Jekyll .md to .html: contains the patterns for converting .md extension to .html used by Jekyll.

• For Type Jekyll Front Matter: