python-markdown / github-links

Python-Markdown GitHub Links Extension

Python-Markdown Github-Links Extension

An extension to Python-Markdown which adds support for shorthand links to GitHub users, repositories, issues and commits.

Installation

To install the extension run the following command:

pip install mdx-gh-links

Usage

To use the extension simply include its name in the list of extensions passed to Python-Markdown.

import markdown
markdown.markdown(src, extensions=['mdx_gh_links'])

Configuration Options

To set configuration options, you may pass them to Markdown's exension_configs keyword...

markdown.markdown(
    src,
    extensions=['mdx_gh_links'],
    extension_configs={
        'mdx_gh_links': {'user': 'foo', 'repo': 'bar'}
    }
)

... or you may import and pass the configs directly to an instance of the mdx_gh_links.GithubLinks class...

from mdx_gh_links import GithubLinks
markdown.markdown(src, extensions=[GithubLinks(user='foo', repo='bar')])

The following configuration options are available:

user

A GitHub user name or organization. If no user or organization is specified in a GitHub link, then the value of this option will be used.

repo

A GitHub repository. If no repository is specified in a GitHub link, then the value of this option will be used.

domain

The domain of the host server for the repository. Defaults to https://github.com, but may be set to the root of a GitHub Enterprise Server.

Syntax

This extension implements shorthand to specify links to GitHub in various ways.

All links in the generated HTML are assigned a gh-link class as well as a class unique to that type of link. See each type for the specific class assigned.

Mentions

Link directly to a GitHub user, organization or repository. Note that no verification is made that an actual user, organization or repository exists. As the syntax does not differentiate between users and organizations, all organizations are assumed to be users. However, this assumption is only reflected in the title of a link.

Mentions use the format @{user} to link to a user or organization and @{user}/{repo} to link to a repository. The defaults defined in the configuration options are ignored by mentions. A mention may be escaped by adding a backslash immediately before the at sign (@).

All mentions are assigned the gh-mention class.

The following table provides some examples:

shorthand	href	rendered result
@foo	https://github.com/foo	@foo
@foo/bar	https://github.com/foo/bar	@foo/bar
\@foo		@foo
\@foo/bar		@foo/bar

Issues

Link directly to a GitHub issue or pull request (PR). Note that no verification is made that an actual issue or PR exists. As the syntax does not differentiate between Issues and PRs, all URLs point to "issues". Fortunately, GitHub will properly redirect an issue URL to a PR URL if appropriate.

Issue links use the format #{num} or {user}/{repo}#{num}. {num} is the number assigned to the issue or PR. {user} and {repo} will use the defaults defined in the configuration options if not provided. An issue link may be escaped by adding a backslash immediately before the hash mark (#).

All issue links are assigned the gh-issue class.

The following table provides various examples (with the defaults set as user='user', repo='repo'):

shorthand	href	rendered result
#123	https://github.com/user/repo/issues/123	#123
foo/bar#123	https://github.com/foo/bar/issues/123	foo/bar#123
\#123		#123
foo/bar\#123		foo/bar#123

Commits

Link directly to a GitHub Commit. Note that no verification is made that an actual commit exists.

Commit links consist of a complete 40 character SHA hash and may optionally be prefaced by {user}@ or {user/repo}@. {user} and {repo} will use the defaults defined in the configuration options if not provided. To avoid a 40 character hash from being linked, wrap it in a code span.

All commit links are assigned the gh-commit class.

The following table provides various examples (with the defaults set as user='user', repo='repo'):

shorthand	href	rendered result
72df691791fb36f00cf5363fefe757c8d3042656	https://github.com/user/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656	72df691
foo@72df691791fb36f00cf5363fefe757c8d3042656	https://github.com/foo/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656	foo@72df691
foo/bar@72df691791fb36f00cf5363fefe757c8d3042656	https://github.com/foo/bar/commit/72df691791fb36f00cf5363fefe757c8d3042656	foo/bar@72df691
`72df691791fb36f00cf5363fefe757c8d3042656`		72df691791fb36f00cf5363fefe757c8d3042656

License

The Python-Markdown Github-Links Extension is licensed under the BSD License as defined in LICENSE.

Change Log

Version 0.4 (2023/12/22)

Add domain configuration option in order to support GitHub Enterprise Servers.

Version 0.3.1 (2023/07/28)

Include README in release.

Version 0.3 (2022/07/18)

Update dependencies.

Version 0.2 (2018/03/09)

Ignore mentions/issues/commits within Markdown links.

Version 0.1 (2017/11/10)

The initial release.

github-links's Issues

Latest release fails with Markdown 3.4

Cause: Python-Markdown/markdown@a767b2d

Error: ImportError: cannot import name 'etree' from 'markdown.util'

I see that there's an old commit fixing this but it's not included in any release.
7b3a23c

Enable usage on GitHub Enterprise Server (GHES)

This is a follow-up on the discussion in #14.

Text in links should be ignored.

If text is already in a link, it should be ignored. For example. if a document were to contain...

[@waylan](https://example.com/waylan)

The link would be parsed (as it should), and then this extension would parse the link label (@waylan) and nest a second link inside the first one, resulting in the following:

<a href="https://example.com/waylan">
    <a class="gh-link gh-mention" 'href="https://github.com/waylan" title="GitHub User: @waylan">@waylan</a>
</a>

In addition to the wierdness of the nested links, notice that the first link is not a GitHub mention, but something else. Of course as a workaround, you can escape the mention, like this:

[\@waylan](https://example.com/waylan)

But it should be smart enough to not insert a link inside another link. The problem is that Python-Markdown doesn't really provide a way to check that (inline patterns have no access to their parent). And it gets potentially more complicated when there is multiple levels of nesting. Consider this:

[**@waylan**](https://example.com/waylan)

The direct parent is not a link (<a> tag), but an ancestor is. Therefore, the behavior should be the same as if the direct parent was a link.

Latest release is failing (0.4)

Latest release is failing to pick up issues and author references in the form of #123 or @seanbudd

set up:

Markdown==3.5.1
mdx_truly_sane_lists==1.3
markdown-link-attr-modifier==0.2.1
mdx-gh-links==0.4

Note 0.3.1 works fine

Feature request: Support config for URL_BASE

This could be useful for GitHub Enterprise setups (or even Gitlab).

The current workaround is:

import mdx_gh_links

mdx_gh_links.URL_BASE = 'https://ghe.bigcorp.com'
        
m = markdown.markdown(
  some_input,
  extensions=[mdx_gh_links.GithubLinks()],
)