Repository files navigation

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

To install the extension run the following command:

pip install mdx-gh-links

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

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

To set configuration options, you may pass them to Markdown'sexension_configskeyword...

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 themdx_gh_links.GithubLinks class...

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

The following configuration options are available:

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

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

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

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

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

Link directly to a GitHub user, organization or repository. Note that noverification is made that an actual user, organization or repository exists. Asthe syntax does not differentiate between users and organizations, allorganizations are assumed to be users. However, this assumption is onlyreflected 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 theconfiguration options are ignored by mentions. A mention may be escaped byadding a backslash immediately before the at sign (@).

All mentions are assigned thegh-mention class.

The following table provides some examples:

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

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

All issue links are assigned thegh-issue class.

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

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

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

All commit links are assigned thegh-commit class.

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

The Python-Markdown Github-Links Extension is licensed under theBSD License asdefined inLICENSE.

Adddomain configuration option in order to support GitHub Enterprise Servers.

Include README in release.

Update dependencies.

Ignore mentions/issues/commits within Markdown links.

The initial release.