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 the angle bracketed auto-link format as well.
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>
.
Auto-Linking Example
- Just paste links directly in the document like this: https://google.com. - Or even an email address: fake.email@email.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), commits (7d1b190), and compares (e2ed7e0...90b6fb8). You can also reference repositories (facelessuser/pymdown-extensions) and it supports mentioning users (@facelessuser). Mentions also works for social media (only Twitter is supported at this time).
The syntax for repository providers 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. I also preferred the subtle differences in GitLab's commit references as it was consistent with pull and issue syntax.
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.
Warning
Links are not verified, so make sure you are specifying valid issues, repositories, and users as they will be auto-linked even if they are not valid.
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}
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.
Repository Mention Example
@facelessuser/pymdown-extensions @gitlab:pycqa/flake8
Issues and Pull Requests
Issues and pull requests are specified with #{num}
and !{num}
respectively. To specify an issue for a non-default repository under the default user, prefix the repository: {repo}#{num}
. And to specify a repository under a non-default user, prefix both the user and repository: {user}/{repo}#{num}
. And to reference an external provider, use the format {provider}:{user}/{repo}#{num}
. If the default provider is a social media provider, then only the latter syntax can be used.
Issue Example
Issue #1 Issue backrefs#1 Issue Python-Markdown/markdown#1 Issue gitlab:pycqa/flake8#385 Pull request !13 Pull request backrefs!4 Pull request Python-Markdown/markdown!598 Pull request gitlab:pycqa/flake8!213
Issue #1
Issue backrefs#1
Issue Python-Markdown/markdown#1
Issue pycqa/flake8#385
Pull request !13
Pull request backrefs!4
Pull request Python-Markdown/markdown!598
Pull request pycqa/flake8!213
Note
GitHub actually gives pull requests and issues unique values while GitLab and Bitbucket can have pulls with the same ID as an issue. So with GitHub, you can use #{num}
format for both issues and pulls, and GitHub will redirect you to the appropriate issue or pull.
GitLab and Bitbucket must specify pulls different from issues, hence the !13
format. Though GitHub doesn't need to use the pull format, you can if you like. This format was actually borrowed from GitLab.
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.
Commit Example
181c06d1f11fa29961b334e90606ed1f1ec7a7cc backrefs@cb4ecc5e7d8f7cdff0bb4482174f2ff0dcc35c61 Python-Markdown/markdown@de5c696f94e8dde242c29d4be50b7bbf3c17fedb gitlab:pycqa/flake8@8acf55e0f85233c51c291816d73d828cc62d30d1
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}
.
Compare Example
e2ed7e0b3973f3f9eb7a26b8ef7ae514eebfe0d2...90b6fb8711e75732f987982cc024e9bb0111beac backrefs@88c6238a1c2cf71a96eb9abb4b0213f79d6ca81f...cb4ecc5e7d8f7cdff0bb4482174f2ff0dcc35c61 Python-Markdown/markdown@007bd2aa4c184b28f710d041a0abe78bffc0ec2e...de5c696f94e8dde242c29d4be50b7bbf3c17fedb gitlab:pycqa/flake8@1ecf97005a024391fb07ad8941f4d25c4e0aae6e...9bea7576ac33a8e4f72f87ffa81dfa10256fca6e
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. Unfortunately, mention link shortening is not presently supported due to the fact that MagicLink does not use any of the providers' API to verify user links, and some legitimate links can look like user links, but are not.
If we specify long form URLs from external providers, they will be shortened appropriately.
External Provider Example
- https://gitlab.com/pycqa/flake8/issues/385 - https://bitbucket.org/mrabarnett/mrab-regex/issues/260/extremely-slow-matching-using-ignorecase
When specifying links that reference the configured provider
, user
, and repo
, links will be shortened differently in light of that context.
Internal Provider Example
- 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
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.
Link Type | Class |
---|---|
General | magiclink |
Mentions | magiclink-mention |
Repository Mentions | magiclink-repository |
Issues | magiclink-issue |
Pulls | magiclink-pull |
Commits | magiclink-commit |
Compares | magiclink-compare |
GitHub | magiclink-github |
Bitbucket | magiclink-bitbucket |
GitLab | magiclink-gitlab |
magiclink-twitter |
Options
Option | Type | Default | Description |
---|---|---|---|
hide_protocol |
bool | False |
If True , links are displayed without the initial ftp:// , http:// , https:// , or ftps:// . |
repo_url_shortener |
bool | False |
If True , GitHub, Bitbucket, and GitLab commit, pull, and issue links are are rendered in a shorthand syntax. |
repo_url_shorthand |
bool | False |
If True , you can directly use a shorthand syntax to represent commit, pull, issue, and mention links for repository providers and they will be auto-linked. |
social_url_shorthand |
bool | False |
If True , you can directly use a shorthand syntax to represent mention links for social media providers and they will be auto-linked. |
provider |
string | 'github' |
The provider to use for repository shorthand syntax and shortener. |
user |
string | '' |
The default user name to use for the specified provider. |
repo |
string | '' |
The default repository name to use for the specified user and provider. |
labels |
dict | {} |
A dictionary for overriding repository link title text. See labels for more info. |
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' }