Magiclink support for custom autolinked references

[jklukas]

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>'

[facelessuser]

It's an interesting idea. Something to consider possibly for the future.

[jklukas]

Would you be open to considering and reviewing a contribution for this?

[facelessuser]

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.

[facelessuser]

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?

[jklukas]

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.

[facelessuser]

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.

[facelessuser]

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.

[facelessuser]

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...

[facelessuser]

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.

[jklukas]

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.

[facelessuser]

That's fine. In that case, if classes are generated from the prefix, they should be lowercase.

[jklukas]

See #2550 for initial implementation to continue discussion.

[facelessuser]

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.