{!admin-only.md!}
Linkifiers make it easy to refer to issues or tickets in third
party issue trackers, like GitHub, Salesforce, Zendesk, and others.
For instance, you can add a linkifier that automatically turns #2468
into a link to https://github.com/zulip/zulip/issues/2468
.
If the pattern appears in a topic, Zulip adds an Open () button to the right of the topic in the message recipient bar that links to the appropriate URL.
If you have any trouble creating the linkifiers you want, please contact Zulip support with details on what you're trying to do.
{start_tabs}
{settings_tab|linkifier-settings}
-
Under Add a new linkifier, enter a Pattern and URL template.
-
Click Add linkifier.
{end_tabs}
The following examples cover the most common types of linkifiers, with a focus on linkifiers for issues or tickets.
This is a pattern that turns a #
followed by a number into a link. It is often
used to link to issues or tickets in third party issue trackers, like GitHub,
Salesforce, Zendesk, and others.
{start_tabs}
- Pattern:
#(?P<id>[0-9]+)
- URL template:
https://github.com/zulip/zulip/issues/{id}
- Original text:
#2468
- Automatically links to:
https://github.com/zulip/zulip/issues/2468
{end_tabs}
To set up linkifiers for issues or tickets in multiple projects,
consider extending the #2468
format with project-specific
variants. For example, the Zulip development community
uses
#M2468
for an issue in the repository for the Zulip mobile app,
#D2468
and issue in the desktop app repository, etc.
{start_tabs}
- Pattern:
#M(?P<id>[0-9]+)
- URL template:
https://github.com/zulip/zulip-mobile/issues/{id}
- Original text:
#M2468
- Automatically links to:
https://github.com/zulip/zulip-mobile/issues/2468
{end_tabs}
For organizations that commonly link to multiple GitHub repositories, this
linkfier pattern turns org/repo#ID
into an issue or pull request link.
{start_tabs}
- Pattern:
(?P<org>[a-zA-Z0-9_-]+)/(?P<repo>[a-zA-Z0-9_-]+)#(?P<id>[0-9]+)
- URL template:
https://github.com/{org}/{repo}/issues/{id}
- Original text:
zulip/zulip#2468
- Automatically links to:
https://github.com/zulip/zulip/issues/2468
{end_tabs}
The following pattern linkfies a string of hexadecimal digits between 7 and 40 characters long, such as a Git commit ID.
{start_tabs}
- Pattern:
(?P<id>[0-9a-f]{7,40})
- URL template:
https://github.com/zulip/zulip/commit/{id}
- Original text:
abdc123
- Automatically links to:
https://github.com/zulip/zulip/commit/abcd123
{end_tabs}
Linkifiers are a flexible system that can be used to construct rules for a wide variety of situations. Linkifier patterns are regular expressions, using the re2 regular expression engine.
The linkifiers are ordered as they are displayed in the settings. When the regular expressions have an overlapping match, only the earliest one will be used to generate the link. You can reorder the linkifiers by dragging and dropping.
Linkifiers use RFC 6570 compliant
URL templates to describe how links should be generated. These templates support
several expression types. The default expression type ({var}
) will URL-encode
special characters like /
and &
; this behavior is desired for the vast
majority of linkifiers. Fancier URL template expression types can allow you to
get the exact behavior you want in corner cases like optional URL query
parameters. For example:
- Use
{+var}
when you want URL delimiter characters to not be URL-encoded. - Use
{?var}
and{&var}
for variables in URL query parameters. - Use
{#var}
when generating#
fragments in URLs.
The URL template specification has brief examples and detailed examples explaining the precise behavior of URL templates.
This example pattern is a shorthand for linking to pages on Zulip's ReadTheDocs site.
{start_tabs}
- Pattern:
RTD/(?P<article>[a-zA-Z0-9_/.#-]+)
- URL template:
https://zulip.readthedocs.io/en/latest/{+article}
- Original text:
RTD/overview/changelog.html
- Automatically links to:
https://zulip.readthedocs.io/en/latest/overview/changelog.html
{end_tabs}
!!! tip ""
This pattern uses the `{+var}` expression type. With the
default expression type (`{article}`), the `/` between `overview` and
`changelog` would incorrectly be URL-encoded.
This example pattern allows linking to Google searches.
{start_tabs}
- Pattern:
google:(?P<q>\w+)?
- URL template:
https://google.com/search{?q}
- Original text:
google:foo
orgoogle:
- Automatically links to:
https://google.com/search?q=foo
orhttps://google.com/search
{end_tabs}
!!! tip ""
This pattern uses the `{?var}` expression type. With the default expression
type (`{q}`), there would be no way to only include the `?` in the URL
if the optional `q` is present.
These example patterns link to arbitrary repositories in either
the organization zulip-testing
or zulip
. zulip
is only used
when the repo name is not lorem
.
{start_tabs}
-
Linkifier #1
- Pattern:
lorem#(?P<id>[0-9]+)
- URL template:
https://github.com/zulip-testing/lorem/pull/{id}
- Pattern:
-
Linkifier #2
- Pattern:
(?P<repo>[a-zA-Z0-9_-]+)#(?P<id>[0-9]+)
- URL template:
https://github.com/zulip/{repo}/pull/{id}
- Pattern:
-
Example matching linkifier #1 and #2
- Original text:
lorem#123
- Automatically links to:
https://github.com/zulip-testing/lorem/pull/123
- Original text:
-
Example matching linkifier #2 only
- Original text:
zulip-flutter#123
- Automatically links to:
https://github.com/zulip/zulip-flutter/pull/123
- Original text:
{end_tabs}
!!! tip ""
This set of patterns have overlapping regular expressions. Note that
`(?P<repo>[a-zA-Z0-9_-]+)#(?P<id>[0-9]+)` would match `lorem#123` too.
Linkifier #1 gets prioritized over linkifier #2 because it is
ordered before the linkifier #2. This order can be customized by
dragging and dropping the linkifiers.