Linker

Bitbucket supports converting arbitrary user-supplied strings in the UI to links if they match a pre-defined pattern. The linkers module allows your app to supply a regular expression and a corresponding URL, so that when a match in a user-supplied string is found, the matched text is converted to a link or image using the supplied URL.

This module can either match all occurrences of the supplied regular expression, or it can match based on values supplied via the Bitbucket API

Matching regular expressions

Take the following example (simplified) descriptor:

1
2
3
4
5
6
7
8
9
10
11
12
13
baseUrl: "https://jira.atlassian.com/",
...
"modules": {
    linkers: [
        {
          "key": "jira-url-linker",
          "regex": "([\w\-]+\-\d+)",
          "url": "/browse/\1",
          "type": "href"
        }
    ]
}

And the following text: The issue this resolves is BB-1234

Bitbucket would automatically convert BB-1234 into a link with an href of https://jira.atlassian.com/browse/BB-1234.

Using the Bitbucket API to supply values

If you don't want your app to linkify every matching value, you can provide a values list with the Bitbucket API. When used in combination with a Bitbucket specific match group, only the matching values will be linkified.

Below, we've added the Bitbucket specific match group (?K) to our example descriptor. (?K) is converted internally to the regular expression ([\w\-]+). All values input through the API must also match this pattern.

1
2
3
4
5
6
7
8
9
10
11
12
13
baseUrl: "https://jira.atlassian.com/",
...
"modules": {
    linkers: [
        {
          "key": "jira-url-linker",
          "regex": "((?K)\-\d+)",
          "url": "/browse/\1",
          "type": "href"
        }
    ]
}

And the following text: The issue this resolves is BB-1234 and OPS-23

If your app only supplied the linker value BB, then only the BB-1234 matched text would be linkified.

Properties

key
Type
Required
Yes
Description

A unique key within the app.


regex
Type
Required
Yes
Description

A regular expression to run against the target text to define a link. The regex syntax is expanded to include (?K). The specified token values will be substituted for (?K) when matching the regular expression.


url
Type
Required
Yes
Description

The url used to replace the matching result of the regex. Backreferences to the match are included, (?K) groups are considered a match group.


conditions
Type
Description

Conditions control whether or not a module will be displayed based on the current context. See Conditions for more details


context
Type
Allowed values
  • page
  • PAGE
  • addon
  • ADDON
  • product
  • PRODUCT
Description

The context for the URL parameter, if the URL is specified as a relative (not absolute) URL. This context can be either addon, which renders the URL relative to an app's base URL, page which targets a page module by specifying the page's module key as the url or product, which renders the URL relative to the product's base URL.


params
Type

target
Type

type
Type
Allowed values
  • href
Description

The text matching the regex will be converted to an anchor tag. This is the default and only option.