| Name | mdx-gh-links JSON |
| Version |
0.4
JSON |
| download |
| home_page | |
| Summary | An extension to Python-Markdown which adds support for shorthand links to GitHub users, repositories, issues and commits. |
| upload_time | 2023-12-22 19:54:02 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | Python-Markdown Github-Links Extension is Copyright (c) 2017-2018 by Waylan Limberg. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of HTMLTree nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY WAYLAN LIMBERG ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY CONTRIBUTORS TO Github-Links Extension BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
markdown
python-markdown
github
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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:
```sh
pip install mdx-gh-links
```
## Usage
To use the extension simply include its name in the list of extensions passed to
Python-Markdown.
```python
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...
```python
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...
```python
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](https://github.com/foo "GitHub User: @foo") |
| `@foo/bar` | `https://github.com/foo/bar` | [@foo/bar](https://github.com/foo/bar "GitHub Repository: @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](https://github.com/user/repo/issues/123 "GitHub Issue user/repo #123") |
| `foo/bar#123` | `https://github.com/foo/bar/issues/123` | [foo/bar#123](https://github.com/foo/bar/issues/123 "GitHub Issue 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](https://github.com/user/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656 "GitHub Commit: user/repo@72df691791fb36f00cf5363fefe757c8d3042656") |
| `foo@72df691791fb36f00cf5363fefe757c8d3042656` | `https://github.com/foo/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656` | [foo@72df691](https://github.com/foo/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656 "GitHub Commit: foo/repo@72df691791fb36f00cf5363fefe757c8d3042656") |
| `foo/bar@72df691791fb36f00cf5363fefe757c8d3042656` | `https://github.com/foo/bar/commit/72df691791fb36f00cf5363fefe757c8d3042656` | [foo/bar@72df691](https://github.com/foo/bar/commit/72df691791fb36f00cf5363fefe757c8d3042656 "GitHub Commit: foo/bar@72df691791fb36f00cf5363fefe757c8d3042656") |
| `` `72df691791fb36f00cf5363fefe757c8d3042656` `` | | `72df691791fb36f00cf5363fefe757c8d3042656` |
## License
The Python-Markdown Github-Links Extension is licensed under the [BSD License] as
defined in `LICENSE`.
[BSD License]: http://opensource.org/licenses/BSD-3-Clause
## 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "mdx-gh-links",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "markdown,python-markdown,github",
"author": "",
"author_email": "Waylan limberg <waylan.limberg@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/ea/bf1f721a8dc0ff83b426480f040ac68dbe3d7898b096c1277a5a4e3da0ec/mdx_gh_links-0.4.tar.gz",
"platform": null,
"description": "# Python-Markdown Github-Links Extension\n\nAn extension to Python-Markdown which adds support for shorthand links to GitHub\nusers, repositories, issues and commits.\n\n## Installation\n\nTo install the extension run the following command:\n\n```sh\npip install mdx-gh-links\n```\n\n## Usage\n\nTo use the extension simply include its name in the list of extensions passed to\nPython-Markdown.\n\n```python\nimport markdown\nmarkdown.markdown(src, extensions=['mdx_gh_links'])\n```\n\n### Configuration Options\n\nTo set configuration options, you may pass them to Markdown's `exension_configs`\nkeyword...\n\n```python\nmarkdown.markdown(\n src,\n extensions=['mdx_gh_links'],\n extension_configs={\n 'mdx_gh_links': {'user': 'foo', 'repo': 'bar'}\n }\n)\n```\n\n... or you may import and pass the configs directly to an instance of the\n`mdx_gh_links.GithubLinks` class...\n\n```python\nfrom mdx_gh_links import GithubLinks\nmarkdown.markdown(src, extensions=[GithubLinks(user='foo', repo='bar')])\n```\n\nThe following configuration options are available:\n\n#### user\n\nA GitHub user name or organization. If no user or organization is specified in\na GitHub link, then the value of this option will be used.\n\n#### repo\n\nA GitHub repository. If no repository is specified in a GitHub link, then the\nvalue of this option will be used.\n\n### domain\n\nThe domain of the host server for the repository. Defaults to\n`https://github.com`, but may be set to the root of a GitHub Enterprise Server.\n\n## Syntax\n\nThis extension implements shorthand to specify links to GitHub in various ways.\n\nAll links in the generated HTML are assigned a `gh-link` class as well as a class\nunique to that type of link. See each type for the specific class assigned.\n\n### Mentions\n\nLink directly to a GitHub user, organization or repository. Note that no\nverification is made that an actual user, organization or repository exists. As\nthe syntax does not differentiate between users and organizations, all\norganizations are assumed to be users. However, this assumption is only\nreflected in the title of a link.\n\nMentions use the format `@{user}` to link to a user or organization and\n`@{user}/{repo}` to link to a repository. The defaults defined in the\nconfiguration options are ignored by mentions. A mention may be escaped by\nadding a backslash immediately before the at sign (`@`).\n\nAll mentions are assigned the `gh-mention` class.\n\nThe following table provides some examples:\n\n| shorthand | href | rendered result |\n| ----------- | ---------------------------- | -------------------------------------------------------------------- |\n| `@foo` | `https://github.com/foo` | [@foo](https://github.com/foo \"GitHub User: @foo\") |\n| `@foo/bar` | `https://github.com/foo/bar` | [@foo/bar](https://github.com/foo/bar \"GitHub Repository: @foo/bar\") |\n| `\\@foo` | | @foo |\n| `\\@foo/bar` | | @foo/bar |\n\n### Issues\n\nLink directly to a GitHub issue or pull request (PR). Note that no verification\nis made that an actual issue or PR exists. As the syntax does not differentiate\nbetween Issues and PRs, all URLs point to \"issues\". Fortunately, GitHub will\nproperly redirect an issue URL to a PR URL if appropriate.\n\nIssue links use the format `#{num}` or `{user}/{repo}#{num}`. `{num}` is the\nnumber assigned to the issue or PR. `{user}` and `{repo}` will use the\ndefaults defined in the configuration options if not provided. An issue link may\nbe escaped by adding a backslash immediately before the hash mark (`#`).\n\nAll issue links are assigned the `gh-issue` class.\n\nThe following table provides various examples (with the defaults set as\n`user='user', repo='repo'`):\n\n| shorthand | href | rendered result |\n| -------------- | -------------------------------------------- | ----------------------------------------------------------------------------------- |\n| `#123` | `https://github.com/user/repo/issues/123` | [#123](https://github.com/user/repo/issues/123 \"GitHub Issue user/repo #123\") |\n| `foo/bar#123` | `https://github.com/foo/bar/issues/123` | [foo/bar#123](https://github.com/foo/bar/issues/123 \"GitHub Issue foo/bar #123\") |\n| `\\#123` | | #123 |\n| `foo/bar\\#123` | | foo/bar#123 |\n\n### Commits\n\nLink directly to a GitHub Commit. Note that no verification is made that an\nactual commit exists.\n\nCommit links consist of a complete 40 character SHA hash and may optionally be\nprefaced by `{user}@` or `{user/repo}@`. `{user}` and `{repo}` will use the\ndefaults defined in the configuration options if not provided. To avoid a 40\ncharacter hash from being linked, wrap it in a code span.\n\nAll commit links are assigned the `gh-commit` class.\n\nThe following table provides various examples (with the defaults set as\n`user='user', repo='repo'`):\n\n| shorthand | href | rendered result |\n| -------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `72df691791fb36f00cf5363fefe757c8d3042656` | `https://github.com/user/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656` | [72df691](https://github.com/user/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656 \"GitHub Commit: user/repo@72df691791fb36f00cf5363fefe757c8d3042656\") |\n| `foo@72df691791fb36f00cf5363fefe757c8d3042656` | `https://github.com/foo/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656` | [foo@72df691](https://github.com/foo/repo/commit/72df691791fb36f00cf5363fefe757c8d3042656 \"GitHub Commit: foo/repo@72df691791fb36f00cf5363fefe757c8d3042656\") |\n| `foo/bar@72df691791fb36f00cf5363fefe757c8d3042656` | `https://github.com/foo/bar/commit/72df691791fb36f00cf5363fefe757c8d3042656` | [foo/bar@72df691](https://github.com/foo/bar/commit/72df691791fb36f00cf5363fefe757c8d3042656 \"GitHub Commit: foo/bar@72df691791fb36f00cf5363fefe757c8d3042656\") |\n| `` `72df691791fb36f00cf5363fefe757c8d3042656` `` | | `72df691791fb36f00cf5363fefe757c8d3042656` |\n\n## License\n\nThe Python-Markdown Github-Links Extension is licensed under the [BSD License] as\ndefined in `LICENSE`.\n\n[BSD License]: http://opensource.org/licenses/BSD-3-Clause\n\n## Change Log\n\n### Version 0.4 (2023/12/22)\n\nAdd `domain` configuration option in order to support GitHub Enterprise Servers.\n\n### Version 0.3.1 (2023/07/28)\n\nInclude README in release.\n\n### Version 0.3 (2022/07/18)\n\nUpdate dependencies.\n\n### Version 0.2 (2018/03/09)\n\nIgnore mentions/issues/commits within Markdown links.\n\n### Version 0.1 (2017/11/10)\n\nThe initial release.\n",
"bugtrack_url": null,
"license": "Python-Markdown Github-Links Extension is Copyright (c) 2017-2018 by Waylan Limberg. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of HTMLTree nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY WAYLAN LIMBERG ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY CONTRIBUTORS TO Github-Links Extension BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "An extension to Python-Markdown which adds support for shorthand links to GitHub users, repositories, issues and commits.",
"version": "0.4",
"project_urls": {
"Homepage": "https://pypi.org/project/mdx-gh-links/",
"Issue Tracker": "https://github.com/Python-Markdown/github-links/issues",
"Repository": "https://github.com/Python-Markdown/github-links"
},
"split_keywords": [
"markdown",
"python-markdown",
"github"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5c7ccfe05ade98ba7a63f05d1b05b7508d9af743cbd1f1681aa0c9900a8cd40",
"md5": "ed65644cd2c7fb9ee0d21b33bafb141f",
"sha256": "9057bca1fa5280bf1fcbf354381e46c9261cc32c2d5c0407801f8a910be5f099"
},
"downloads": -1,
"filename": "mdx_gh_links-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed65644cd2c7fb9ee0d21b33bafb141f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7166,
"upload_time": "2023-12-22T19:54:00",
"upload_time_iso_8601": "2023-12-22T19:54:00.384104Z",
"url": "https://files.pythonhosted.org/packages/c5/c7/ccfe05ade98ba7a63f05d1b05b7508d9af743cbd1f1681aa0c9900a8cd40/mdx_gh_links-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2feabf1f721a8dc0ff83b426480f040ac68dbe3d7898b096c1277a5a4e3da0ec",
"md5": "ea7a7385c32df26e0b2d81f85a579557",
"sha256": "41d5aac2ab201425aa0a19373c4095b79e5e015fdacfe83c398199fe55ca3686"
},
"downloads": -1,
"filename": "mdx_gh_links-0.4.tar.gz",
"has_sig": false,
"md5_digest": "ea7a7385c32df26e0b2d81f85a579557",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5783,
"upload_time": "2023-12-22T19:54:02",
"upload_time_iso_8601": "2023-12-22T19:54:02.136430Z",
"url": "https://files.pythonhosted.org/packages/2f/ea/bf1f721a8dc0ff83b426480f040ac68dbe3d7898b096c1277a5a4e3da0ec/mdx_gh_links-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-22 19:54:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Python-Markdown",
"github_project": "github-links",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdx-gh-links"
}
