# mdformat-gfm-alerts
[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]
<!-- [![codecov.io][cov-badge]][cov-link]
[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-gfm-alerts/branch/main/graph/badge.svg
[cov-link]: https://codecov.io/gh/executablebooks/mdformat-gfm-alerts
-->
An [mdformat](https://github.com/executablebooks/mdformat) plugin for [GitHub "Alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). "Alerts" are a block quote variation of admonitions that were proposed in this [community discussion](https://github.com/orgs/community/discussions/16925) and are currently a separate extension of the [GFM (GitHub-Flavored Markdown) syntax](https://github.github.com/gfm).
## `mdformat` Usage
Add this package wherever you use `mdformat` and the plugin will be auto-recognized. No additional configuration necessary. See [additional information on `mdformat` plugins here](https://mdformat.readthedocs.io/en/stable/users/plugins.html)
### Pre-Commit
```yaml
repos:
- repo: https://github.com/executablebooks/mdformat
rev: 0.7.16
hooks:
- id: mdformat
additional_dependencies:
- mdformat-gfm-alerts
```
### pipx
```sh
pipx install mdformat
pipx inject mdformat mdformat-gfm-alerts
```
## HTML Rendering
To generate HTML output, `gfm_alerts_plugin` can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>
```py
from markdown_it import MarkdownIt
from mdformat_gfm_alerts.mdit_plugins import gfm_alerts_plugin
md = MarkdownIt()
md.use(gfm_alerts_plugin)
text = "> [!NOTE]\n> Useful information that users should know, even when skimming content. "
md.render(text)
# <blockquote>
# <div class="markdown-alert markdown-alert-note">
# <p class="markdown-alert-title">Note</p>
# <p>Useful information that users should know, even when skimming content.</p>
# </div>
# </blockquote>
```
> **Warning**
>
> This package does not properly handle replacing the `blockquote` outer `div` with a `div` for accessibility. This should be possible with `markdown-it`, but I haven't yet found a way.
## Contributing
See [CONTRIBUTING.md](https://github.com/KyleKing/mdformat-gfm-alerts/blob/main/CONTRIBUTING.md)
[ci-badge]: https://github.com/kyleking/mdformat-gfm-alerts/workflows/CI/badge.svg?branch=main
[ci-link]: https://github.com/kyleking/mdformat-gfm-alerts/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
[pypi-badge]: https://img.shields.io/pypi/v/mdformat-gfm-alerts.svg
[pypi-link]: https://pypi.org/project/mdformat-gfm-alerts
Raw data
{
"_id": null,
"home_page": null,
"name": "mdformat_gfm_alerts",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "mdformat,markdown,markdown-it",
"author": null,
"author_email": "Kyle King <dev.act.kyle@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1f/98/9a9f05f3f00ee65c8aa9dbbd4cef1c61942dfa9631accfb664702c7ee8d7/mdformat_gfm_alerts-0.0.1.tar.gz",
"platform": null,
"description": "# mdformat-gfm-alerts\n\n[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]\n\n<!-- [![codecov.io][cov-badge]][cov-link]\n[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-gfm-alerts/branch/main/graph/badge.svg\n[cov-link]: https://codecov.io/gh/executablebooks/mdformat-gfm-alerts\n -->\n\nAn [mdformat](https://github.com/executablebooks/mdformat) plugin for [GitHub \"Alerts\"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). \"Alerts\" are a block quote variation of admonitions that were proposed in this [community discussion](https://github.com/orgs/community/discussions/16925) and are currently a separate extension of the [GFM (GitHub-Flavored Markdown) syntax](https://github.github.com/gfm).\n\n## `mdformat` Usage\n\nAdd this package wherever you use `mdformat` and the plugin will be auto-recognized. No additional configuration necessary. See [additional information on `mdformat` plugins here](https://mdformat.readthedocs.io/en/stable/users/plugins.html)\n\n### Pre-Commit\n\n```yaml\nrepos:\n - repo: https://github.com/executablebooks/mdformat\n rev: 0.7.16\n hooks:\n - id: mdformat\n additional_dependencies:\n - mdformat-gfm-alerts\n```\n\n### pipx\n\n```sh\npipx install mdformat\npipx inject mdformat mdformat-gfm-alerts\n```\n\n## HTML Rendering\n\nTo generate HTML output, `gfm_alerts_plugin` can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>\n\n```py\nfrom markdown_it import MarkdownIt\n\nfrom mdformat_gfm_alerts.mdit_plugins import gfm_alerts_plugin\n\nmd = MarkdownIt()\nmd.use(gfm_alerts_plugin)\n\ntext = \"> [!NOTE]\\n> Useful information that users should know, even when skimming content. \"\nmd.render(text)\n# <blockquote>\n# <div class=\"markdown-alert markdown-alert-note\">\n# <p class=\"markdown-alert-title\">Note</p>\n# <p>Useful information that users should know, even when skimming content.</p>\n# </div>\n# </blockquote>\n```\n\n> **Warning**\n>\n> This package does not properly handle replacing the `blockquote` outer `div` with a `div` for accessibility. This should be possible with `markdown-it`, but I haven't yet found a way.\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/KyleKing/mdformat-gfm-alerts/blob/main/CONTRIBUTING.md)\n\n[ci-badge]: https://github.com/kyleking/mdformat-gfm-alerts/workflows/CI/badge.svg?branch=main\n[ci-link]: https://github.com/kyleking/mdformat-gfm-alerts/actions?query=workflow%3ACI+branch%3Amain+event%3Apush\n[pypi-badge]: https://img.shields.io/pypi/v/mdformat-gfm-alerts.svg\n[pypi-link]: https://pypi.org/project/mdformat-gfm-alerts\n",
"bugtrack_url": null,
"license": null,
"summary": "An mdformat plugin for `gfm_alerts`.",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/KyleKing/mdformat-gfm-alerts"
},
"split_keywords": [
"mdformat",
"markdown",
"markdown-it"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fbb6726237108f1d5f77252c9ade49d3fde606878416c96e0d9ec678499ed09d",
"md5": "a7e01b8a89b143dd853e7d26b153c67b",
"sha256": "ca5854921f700dca55dffda233564314545af9dda8fb05a64915ca305dc53469"
},
"downloads": -1,
"filename": "mdformat_gfm_alerts-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7e01b8a89b143dd853e7d26b153c67b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 7788,
"upload_time": "2024-03-10T19:10:01",
"upload_time_iso_8601": "2024-03-10T19:10:01.527461Z",
"url": "https://files.pythonhosted.org/packages/fb/b6/726237108f1d5f77252c9ade49d3fde606878416c96e0d9ec678499ed09d/mdformat_gfm_alerts-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1f989a9f05f3f00ee65c8aa9dbbd4cef1c61942dfa9631accfb664702c7ee8d7",
"md5": "a2b4dfe342862761365e0c87f855b848",
"sha256": "44941676b29b0bd90934d76617547d4464879ebd7980833461d7ae0e975a922b"
},
"downloads": -1,
"filename": "mdformat_gfm_alerts-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a2b4dfe342862761365e0c87f855b848",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 9309,
"upload_time": "2024-03-10T19:10:03",
"upload_time_iso_8601": "2024-03-10T19:10:03.924593Z",
"url": "https://files.pythonhosted.org/packages/1f/98/9a9f05f3f00ee65c8aa9dbbd4cef1c61942dfa9631accfb664702c7ee8d7/mdformat_gfm_alerts-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-10 19:10:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KyleKing",
"github_project": "mdformat-gfm-alerts",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mdformat_gfm_alerts"
}
JSON
