mirror of
https://github.com/zulip/zulip.git
synced 2025-11-15 03:11:54 +00:00
7ce87c66ac
In our current implementation, loose lists and tight lists look the same visually. Loose lists are lists with blank lines between list items, and the contents of a list item should be enclosed in a paragraph tag in that case. For unordered lists, paragraph tags have a bottom margin in starlight and thus looses lists look much more spaced out than tight lists. That is not the behaviour we had in mind while writing the documentation, the reason we had all these loose lists is to make the documentation easy to write and read. So we attempt to remove all the blank lines and fix the problem at source. Since paragraph tags are used for other purposes in a list in starlight, it won't be a wise decision to let the source be as is and just change things in css, other expected behaviours might break in that case. See this topic for more details: https://chat.zulip.org/#narrow/channel/19-documentation/topic/new.20help.20center.3A.20regressions/near/2226084 All the changes were made by a one-off script which has not been commited to the repo. The script wasn't perfect and could not decide between blank lines that make a list loose vs blank lines necessary for a sub-list or a code block inside a list item. A manual review of all the changes was done before making this commit to ensure that no unintended changes were made to the help center files.
209 lines
7.1 KiB
Markdown
209 lines
7.1 KiB
Markdown
# Add a custom linkifier
|
|
|
|
{!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** (<i class="zulip-icon zulip-icon-external-link"></i>) 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}
|
|
|
|
{settings_tab|linkifier-settings}
|
|
|
|
1. Under **Add a new linkifier**, enter a **Pattern** and
|
|
**URL template**.
|
|
|
|
1. Click **Add linkifier**.
|
|
|
|
{end_tabs}
|
|
|
|
## Reorder linkifiers
|
|
|
|
Linkifiers are processed in order, and will not apply to text that
|
|
is already linkified. You can therefore choose which linkifiers to prioritize
|
|
when more than one linkifier applies. See the
|
|
[overlapping patterns section](#overlapping-patterns) for examples.
|
|
|
|
{start_tabs}
|
|
|
|
{settings_tab|linkifier-settings}
|
|
|
|
1. Under **Linkifiers**, click and drag the vertical dots to reorder the list of
|
|
linkifiers.
|
|
|
|
{end_tabs}
|
|
|
|
## Common linkifier patterns
|
|
|
|
The following examples cover the most common types of linkifiers, with a focus
|
|
on linkifiers for issues or tickets.
|
|
|
|
### 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<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}
|
|
|
|
### Link to issues or tickets in multiple projects or apps
|
|
|
|
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<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}
|
|
|
|
### 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<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}
|
|
|
|
### 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<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}
|
|
|
|
## 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.
|
|
|
|
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 <code>{#var}</code> 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<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.
|
|
|
|
### Linking to Google search results
|
|
|
|
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` 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.
|
|
|
|
### Overlapping patterns
|
|
|
|
In this example, a general linkifier is configured to make GitHub
|
|
repository references like `zulip-desktop#123` link to issues in that
|
|
repository within the `zulip` GitHub organization. A more specific
|
|
linkifier overrides that linkifier for a specific repository of
|
|
interest (`django/django`) that is in a different organization.
|
|
|
|
{start_tabs}
|
|
|
|
* Specific linkifier (ordered before the general linkifier)
|
|
* Pattern: `django#(?P<id>[0-9]+)`
|
|
* URL template: `https://github.com/django/django/pull/{id}`
|
|
* General linkifier
|
|
* Pattern: `(?P<repo>[a-zA-Z0-9_-]+)#(?P<id>[0-9]+)`
|
|
* URL template: `https://github.com/zulip/{repo}/pull/{id}`
|
|
* Example matching both linkifiers; specific linkifier takes precedence:
|
|
* Original text: `django#123`
|
|
* Automatically links to: `https://github.com/django/django/pull/123`
|
|
* Example matching only the general linkifier:
|
|
* Original text: `zulip-desktop#123`
|
|
* Automatically links to: `https://github.com/zulip/zulip-desktop/pull/123`
|
|
|
|
{end_tabs}
|
|
|
|
!!! tip ""
|
|
|
|
This set of patterns has overlapping regular expressions. Note that
|
|
the general linkifier pattern would match `lorem#123` too. The specific
|
|
linkifier will only get prioritized over the general linkifier if it is
|
|
ordered before the more general pattern. This can be customized by
|
|
dragging and dropping existing linkifiers into the desired order. New
|
|
linkifiers will automatically be ordered last.
|