From 7ae7b753dac6edc116a0351be7957748a31c8195 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Thu, 27 Apr 2023 13:37:40 -0700 Subject: [PATCH] help: Improve /help/add-a-custom-linkifier page. - Structure page around linkifier use cases. - Add documentation (with examples) for advanced lnkifier types. - Put examples in to tabs blocks. --- help/add-a-custom-linkifier.md | 129 ++++++++++++++++++++++++++++----- 1 file changed, 112 insertions(+), 17 deletions(-) diff --git a/help/add-a-custom-linkifier.md b/help/add-a-custom-linkifier.md index 741ea5a47d..4e7332b1be 100644 --- a/help/add-a-custom-linkifier.md +++ b/help/add-a-custom-linkifier.md @@ -7,14 +7,13 @@ 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`. -Linkifiers use [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) -compliant URL templates to represent the link to be generated from the -pattern. - 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](/help/contact-support) with details on what you're trying to do. + ### Add a custom linkifier {start_tabs} @@ -28,35 +27,131 @@ topic in the message recipient bar that links to the appropriate URL. {end_tabs} -## Understanding linkification patterns +## Common linkifier patterns -This is best explained by example. +The following examples cover the most common types of linkifiers, with a focus +on linkifiers for issues or tickets. -Hash followed by a number of any length. +### Link to an issue or ticket + +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[0-9]+)` * URL template: `https://github.com/zulip/zulip/issues/{id}` * Original text: `#2468` * Automatically links to: `https://github.com/zulip/zulip/issues/2468` -String of hexadecimal digits between 7 and 40 characters long. +{end_tabs} -* Pattern: `(?P[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` +### Link to issues or tickets in multiple projects or apps -Generic GitHub `org/repo#ID` format: +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](https://zulip.com/development-community/#linking-to-github-issues-and-pull-requests) +`#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[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} + +### Link to issues or tickets in multiple repositories + +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[a-zA-Z0-9_-]+)/(?P[a-zA-Z0-9_-]+)#(?P[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` -Linkifier patterns are regular expressions, using the +{end_tabs} + +### Link to a hexadecimal issue or ticket number + +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[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} + +## Advanced linkifier patterns + +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](https://github.com/google/re2/wiki/Syntax) regular expression engine. -If you have any trouble setting these up, please [contact -us](/help/contact-support) with details on what you're trying to do, -and we'll be happy to help you out. +Linkifiers use [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) 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](https://www.rfc-editor.org/rfc/rfc6570.html#section-1.2) and [detailed +examples](https://www.rfc-editor.org/rfc/rfc6570.html#section-3.2) explaining +the precise behavior of URL templates. + +### Linking to documentation pages + +This example pattern is a shorthand for linking to pages on Zulip's ReadTheDocs +site. + +{start_tabs} + +* Pattern: `RTD/(?P
[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. + +### Linking to Google search results + +This example pattern allows linking to Google searches. + +{start_tabs} + +* Pattern: `google:(?P\w+)?` +* URL template: `https://google.com/search{?q}` +* Original text: `google:foo` or `google:` +* Automatically links to: `https://google.com/search?q=foo` or `https://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.