MagicLink

Overview

MagicLink is an extension that provides a number of useful link related features. MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format. MagicLink can also be configured to directly auto-link the aforementioned shorthand format.

If you happen to have some conflicts with syntax for a specific case, you can always revert to the old auto-link format as well: <https://www.link.com>. If enabled, repository link shortening will be applied to the angle bracketed auto-link format as well.

The MagicLink extension can be included in Python Markdown by using the following:

import markdown
md = markdown.Markdown(extensions=['pymdownx.magiclink'])

Auto-Linking

MagicLink supports auto-linking HTTP, FTP and email links. You can specify these links in raw text and they should get auto-linked. There are some limitations placed on MagicLink to keep it from aggressively auto-linking text that is not part of links. If you have a link that cannot be detected, you can always use the old style angle bracketed link format: <https://www.link.com>.

- Just paste links directly in the document like this: https://google.com.
- Or even an email address: fake.email@email.com.

Shorthand Links

MagicLink supports shorthand references for GitHub, GitLab, and Bitbucket issues (#1), pull/merge requests (!13), GitHub Discussion (?1173), commits (7d1b190), and compares (e2ed7e0...90b6fb8). You can also reference repositories (facelessuser/pymdown-extensions) and users (@facelessuser). Mentions also works for social media (only X is supported at this time).

The syntax used is actually very similar to GitLab's syntax. GitLab was chosen as its syntax bridges the gaps between the three providers. GitLab and Bitbucket require a pull specific syntax while GitHub does not have one. Also, while GitHub uses #<num> for issues, pulls, and discussions, the idea of using a different symbol for issue types gives us the context we need to generate the correct links for issues vs pulls, etc.

Configuring

To enable shorthand syntax for code repository providers and social media providers, enable repo_url_shorthand and social_url_shorthand respectively in the options.

To use this feature you must first specify in the options your provider to which all shorthand references are relative to, but you will still be able to reference outside of your defaults. And if you are specifying a code repository provider as your default, you must also specify the user and repo (repository) which adds more context and allows you to shorten the syntax even more for issues relating to your default user and/or repo. This is useful if you are using MagicLink to write documentation for a project that is hosted on one of the supported code repository providers.

If you are using this extension more generally, it may make more sense to set a social media provider as the default provider. There is no need to set a user or repo for a social media provider as the context is not useful for mentions. You will still be able to reference repository links with shorthand if it enabled, albeit in a longer format.

Mentions

Mentions of other users are performed with the following syntax: @{user}. To reference a provider other than your default, use the format @{provider}:{user}

@facelessuser

@x:x

For code repository providers, you can also mention repositories. This feature is actually inspired by the GitHub only extension Python-Markdown/github-links, which performs similar auto-linking. The syntax to auto-link a repository with mentioning is very similar to auto-linking a user, except you append the repository to the user name like so: @{user}/{repo}. If specifying a non-default provider, the form would look like: @{provider}:{user}/{repo}. The output for repository mentions omits the @ symbol and will just show the user and repository, but you are free to style it with CSS to make it stand out more like has been done in this document.

@facelessuser/pymdown-extensions

@gitlab:pycqa/flake8-engine

Issues, Pull Requests, and Discussions

Issues, pull requests, and GitHub discussions are specified with #{num}, !{num}, and ?{num} respectively. When specified in this manner, the links will assume the default repository and default user for generated links.

To specify an issue for a non-default repository under the default user, prefix the repository: {repo}#{num}.

To specify a repository under a non-default user, prefix both the user and repository: {user}/{repo}#{num}.

Lastly, to reference an external provider, use the format {provider}:{user}/{repo}#{num}.

The syntax was borrowed and adapted from GitLab as they use !{num} for pulls and #{num} for issues, ?{num} is our own take for discussions. This syntax was mainly used to ensure we could provide context to the link generator. When rendering the actual links in your documents, it will use the syntax associated with the specified provider. If this is unsatisfactory, you can override this behavior with the icons option and all links will use the same specified convention on output regardless of the provider.

#1

backrefs#1

Python-Markdown/markdown#1

gitlab:pycqa/flake8-engine#21

!13

backrefs!4

Python-Markdown/markdown!598

gitlab:pycqa/infrastructure!1

Commits

Commit shorthand syntax is simply the 40 character commit hash value: {hash}. And much like issues and pull requests, you can denote a repository under the default user with {repo}@{hash} and a repository under a non-default user with {user}/{repo}@{hash}. Lastly, to reference an external provider, use the format {provider}:{user}/{repo}@{hash}. If the default provider is a social media provider, then only the latter syntax can be used.

181c06d1f11fa29961b334e90606ed1f1ec7a7cc

backrefs@cb4ecc5e7d8f7cdff0bb4482174f2ff0dcc35c61

Python-Markdown/markdown@de5c696f94e8dde242c29d4be50b7bbf3c17fedb

gitlab:pycqa/flake8-engine@ee18ac981e3dbaf3365a817663834c7b547f83cb

Diff/Compare

GitLab offers a useful shorthand to specify links to compare differences between two commits. This has been adopted for all the supported repository providers.

Specifying a compare link is very similar to specifying a commit link except you must specify the older hash and the newer hash separated by ...: {hash1}...{hash2}. To specify a compare for a non-default repository under the default user, prefix the repository: {repo}@{hash1}...{hash2}. And to specify a compare under a non-default user, prefix both the user and repository: {user}/{repo}@{hash1}...{hash2}. Lastly, to reference an external provider, use the format {provider}:{user}/{repo}@{hash1}...{hash2}.

e2ed7e0b3973f3f9eb7a26b8ef7ae514eebfe0d2...90b6fb8711e75732f987982cc024e9bb0111beac

backrefs@88c6238a1c2cf71a96eb9abb4b0213f79d6ca81f...cb4ecc5e7d8f7cdff0bb4482174f2ff0dcc35c61

Python-Markdown/markdown@007bd2aa4c184b28f710d041a0abe78bffc0ec2e...de5c696f94e8dde242c29d4be50b7bbf3c17fedb

gitlab:pycqa/flake8-engine@0b063a10249558ede919bcd7f67c6aa563ba74ab...ee18ac981e3dbaf3365a817663834c7b547f83cb

Repository Link Shortener

MagicLink can also recognize issue, pull request, commit, and compare links, and render them in the same output format as the repository shortcut links feature.

If we specify long form URLs from external providers, they will be shortened appropriately.

-   https://github.com/facelessuser
-   https://github.com/facelessuser/pymdown-extensions
-   https://gitlab.com/pycqa/flake8-engine/-/issues/21
-   https://bitbucket.org/mrabarnett/mrab-regex/issues/260/extremely-slow-matching-using-ignorecase

When specifying links that reference the configured provider, user, and repo, some links will be shortened differently in light of that context.

-   https://github.com/facelessuser/pymdown-extensions/issues/1
-   https://github.com/facelessuser/pymdown-extensions/pull/13
-   https://github.com/facelessuser/pymdown-extensions/commit/3f6b07a8eeaa9d606115758d90f55fec565d4e2a
-   https://github.com/facelessuser/pymdown-extensions/compare/e2ed7e0b3973f3f9eb7a26b8ef7ae514eebfe0d2...90b6fb8711e75732f987982cc024e9bb0111beac
-   https://github.com/facelessuser/Rummage/commit/181c06d1f11fa29961b334e90606ed1f1ec7a7cc

MagicLink will shorten user name and repository name links, but every site has some links that will conflict, or better stated, will have links that follow the pattern of user name and repository name links, but are not actually either. For example, https://github.com/support is not a user name, nor are any links under support repository names. By default, MagicLink has provided a list of exclusions for each provider to avoid treating such links as a user name or repository name. You can override them and add more via the option shortener_user_exclude.

Custom Repository Hosts

It is possible that someone may be running their own private GitHub, GitLab, or Bitbucket repository. MagicLink allows for the creating variants of either of these repository providers with a custom host. MagicLink provides no additional control over specifics, so if this is sufficient for your needs, then it give it a try!

To specify a custom provider, you simply need to specify them via the custom option.

1. Simply specify the name to identify the provider (must only contain alphanumeric characters). Provider name is used when manually specifying a provider (@provider:user) and will be used to generate custom CSS classes magiclink-provider.
2. Specify the type. Is this a private github, gitlab, or bitbucket provider.
3. Specify the label for tooltips.
4. Specify the host for your private repository.

'custom': {
    'test': {
        'host': 'http://test.com',
        'label': 'Test',
        'type': 'github'
    }
}

Host URLs assume the www subdomain, and will generate the URL pattern to capture explicit or implicit www in host URLs, whether you specify it in the host URL or not. If your repository does not use www subdomain, then set the option www to False. Most people will never need to touch this.

Lastly, shortener_user_exclude will assume your custom provider requires the same exclude list of the specified type and will copy them for your custom repository. If this is not sufficient, you can add an entry to shortener_user_exclude for your custom repository provider using your specified name. If you manually set excludes in this manner, no excludes from the same type will be copied over.

CSS

For normal links, no classes are added to the anchor tags. For repository links, magiclink will be added as a class. Also, an additional class will be added for each repository link type and provider.

Options

User Excludes

Defaults for shortener_user_exclude:

{
    "bitbucket": ['dashboard', 'account', 'plans', 'support', 'repo'],
    "github": ['marketeplace', 'notifications', 'issues', 'pull', 'sponsors', 'settings', 'support'],
    "gitlab": ['dashboard', '-', 'explore', 'help', 'projects'],
    "x": ['i', 'messages', 'bookmarks', 'home']
}

When overriding, only the providers that are explicitly provided get overridden.

Labels

By default, MagicLink provides titles for the repository links in the form {provider} {label}: {info}. You can specify different values for {label} by configuring the labels option.

The default values are:

    {
        'commit': 'Commit',
        'compare': 'Compare',
        'issue': 'Issue',
        'pull': 'Pull Request',
        'mention': 'User',
        'repository': 'Repository'
    }

You only need to provide the options you wish to override. Assume we wanted to adopt the GitLab terminology for pull requests, we could simply set labels to:

    {
        'pull': 'Merge Request'
    }