facelessuser
Magiclink support for custom autolinked references
Description
It would be great for magiclink to give users the ability to configure auto-linking of additional references specific to their context. The biggest use case here would be for external ticketing systems like Jira or Zendesk.
Benefits
This would greatly expand the potential uses of magiclink since it lets users configure additional providers without magiclink having any specific support for that provider.
Solution Idea
GitHub allows this kind of configuration of custom "autolinked references". See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources
That interface strikes a nice balance between simplicity and customizability. It supports only patterns like <prefix><num> where the <prefix> is static and the <num> is a captured value (either numeric or alphanumeric) that can be injected into the output pattern.
We would add configuration that follows a similar pattern. Something like:
custom_refs:
- identifier_type: numeric
reference_prefix: JIRA-
# Must include <num> to indicate where to inject the identifier
target_url: 'https://jira.example.com/issue?query=<num>'
It's an interesting idea. Something to consider possibly for the future.
I would be open to it. I haven't really thought about the specific details and constraints, but a PR would give us a starting point and move feature inclusion along faster.
One thing I'm curious about, this feature, doors it just convert short names to URLs or is it also supposed convert full URLs to these short-handed as well?
One thing I'm curious about, this feature, doors it just convert short names to URLs or is it also supposed convert full URLs to these short-handed as well?
The GitHub feature is only one-way. It doesn't replace full URLs with the shortened version. Although that would be nice to have as an option.
Okay, I think for now, prefix should be alphanumeric and allow hyphens. An empty prefix should not be allowed. I'm not sure if we need to restrict prefixes to start with alpha, so we can skip that for now. We won't bother with the reverse translation initially to keep things simple. Processing of special links should have a priority after the defaults.
That's probably my initial guidance as of now. Change should have tests.
The bulk of the complexity is likely just in the setup, the actual capturing and replace part should be pretty easy.
I guess prefixt should be case sensitive? I don't know how the reference implementation treats such things... My initial though is sensitive, but I'm open to hearing reasons for insensitive handling.
Classes should be attached to the final link and should mirror how other links are handled. The custom specific class can likely be derived from the prefix (removing trailing hyphens). I guess we could allow class override, but if so, probably prefix them with "magiclink-" for consistency if we do allow that.
I think that's everything...
Oh, I think it is also important to make sure these short codes are handled after normal link handling. We were don't want to capture such short codes inside a URL. Obviously was want to consider word boundary restrictions, but you may accidentally find such codes with reasonably word boundaries in a URL.
I guess prefix should be case sensitive?
The reference implementation is not case sensitive. So JIRA-123 and jira-123 would both match the same rule. My preference would be to match that.
That's fine. In that case, if classes are generated from the prefix, they should be lowercase.
Sounds good. I probably won't have a chance to dig in until this weekend, but I'll take a look as soon as I can.
Some more info gathering on the GitHub autolink references feature, based on error messages:
Reference prefix must begin with a letter and Reference prefix must only contain letters, numbers, or .-_+=:/#
Target URL is missing a
token
Okay, so it seems they do require them to start with letters as I was mentioning but allow a few more additional characters as well.