| Name | mdformat JSON |
| Version |
0.7.17
JSON |
| download |
| home_page | |
| Summary | CommonMark compliant Markdown formatter |
| upload_time | 2023-08-25 10:12:30 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2021 Taneli Hukkinen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
mdformat
markdown
commonmark
formatter
pre-commit
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
[](https://mdformat.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/executablebooks/mdformat/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)
[](https://codecov.io/gh/executablebooks/mdformat)
[](https://pypi.org/project/mdformat)
# 
> CommonMark compliant Markdown formatter
</div>
<!-- start mini-description -->
Mdformat is an opinionated Markdown formatter
that can be used to enforce a consistent style in Markdown files.
Mdformat is a Unix-style command-line tool as well as a Python library.
<!-- end mini-description -->
Find out more in the [docs](https://mdformat.readthedocs.io).
<!-- start installing -->
## Installing
Install with [CommonMark](https://spec.commonmark.org/current/) support:
```bash
pip install mdformat
```
Install with [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) support:
```bash
pip install mdformat-gfm
```
Note that GitHub's Markdown renderer supports syntax extensions not included in the GFM specification.
For full GitHub support do:
```bash
pip install mdformat-gfm mdformat-frontmatter mdformat-footnote
```
Install with [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) support:
```bash
pip install mdformat-myst
```
<!-- end installing -->
<!-- start cli-usage -->
## Command line usage
### Format files
Format files `README.md` and `CHANGELOG.md` in place
```bash
mdformat README.md CHANGELOG.md
```
Format `.md` files in current working directory recursively
```bash
mdformat .
```
Read Markdown from standard input until `EOF`.
Write formatted Markdown to standard output.
```bash
mdformat -
```
### Check formatting
```bash
mdformat --check README.md CHANGELOG.md
```
This will not apply any changes to the files.
If a file is not properly formatted, the exit code will be non-zero.
### Options
```console
foo@bar:~$ mdformat --help
usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]
CommonMark compliant Markdown formatter
positional arguments:
paths files to format
options:
-h, --help show this help message and exit
--check do not apply changes to files
--version show program's version number and exit
--number apply consecutive numbering to ordered lists
--wrap {keep,no,INTEGER}
paragraph word wrap mode (default: keep)
--end-of-line {lf,crlf,keep}
output file line ending mode (default: lf)
```
<!-- end cli-usage -->
## Documentation
This README merely provides a quickstart guide for the command line interface.
For more information refer to the [documentation](https://mdformat.readthedocs.io).
Here's a few pointers to get you started:
- [Style guide](https://mdformat.readthedocs.io/en/stable/users/style.html)
- [Python API usage](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#python-api-usage)
- [Usage as a pre-commit hook](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook)
- [Plugin usage](https://mdformat.readthedocs.io/en/stable/users/plugins.html)
- [Plugin development guide](https://mdformat.readthedocs.io/en/stable/contributors/contributing.html)
- [List of code block formatter plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#existing-plugins)
- [List of parser extension plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#id1)
- [Changelog](https://mdformat.readthedocs.io/en/stable/users/changelog.html)
<!-- start faq -->
## Frequently Asked Questions
### Why not use [Prettier](https://github.com/prettier/prettier) instead?
Mdformat is pure Python code!
Python is pre-installed on macOS and virtually any Linux distribution,
meaning that typically little to no additional installations are required to run mdformat.
This argument also holds true when using together with
[pre-commit](https://github.com/pre-commit/pre-commit) (also Python).
Prettier on the other hand requires Node.js/npm.
Prettier suffers from
[numerous](https://github.com/prettier/prettier/issues?q=is%3Aopen+label%3Alang%3Amarkdown+label%3Atype%3Abug+)
bugs,
many of which cause changes in Markdown AST and rendered HTML.
Many of these bugs are a consequence of using
[`remark-parse`](https://github.com/remarkjs/remark/tree/main/packages/remark-parse)
v8.x as Markdown parser which,
according to the author themselves,
is [inferior to markdown-it](https://github.com/remarkjs/remark/issues/75#issuecomment-143532326) used by mdformat.
`remark-parse` v9.x is advertised as CommonMark compliant
and presumably would fix many of the issues,
but is not used by Prettier (v2.4.0) yet.
Prettier (v2.4.0), being able to format many languages other than Markdown,
is a large package with 65 direct dependencies
(mdformat only has one in Python 3.11+).
This can be a disadvantage in many environments,
one example being size optimized Docker images.
Mdformat's parser extension plugin API allows not only customization of the Markdown specification in use,
but also advanced features like [automatic table of contents generation](https://github.com/hukkin/mdformat-toc).
Also provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.
### What's wrong with the mdformat logo? It renders incorrectly and is just terrible in general.
Nope, the logo is actually pretty great – you're terrible.
The logo is more a piece of art than a logo anyways,
depicting the horrors of poorly formatted text documents.
I made it myself!
That said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome 😄.
<!-- end faq -->
Raw data
{
"_id": null,
"home_page": "",
"name": "mdformat",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "mdformat,markdown,commonmark,formatter,pre-commit",
"author": "",
"author_email": "Taneli Hukkinen <hukkin@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/df/86/6374cc48a89862cfc8e350a65d6af47792e83e7684f13e1222afce110a41/mdformat-0.7.17.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n[](https://mdformat.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/executablebooks/mdformat/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[](https://codecov.io/gh/executablebooks/mdformat)\n[](https://pypi.org/project/mdformat)\n\n# \n\n> CommonMark compliant Markdown formatter\n\n</div>\n\n<!-- start mini-description -->\n\nMdformat is an opinionated Markdown formatter\nthat can be used to enforce a consistent style in Markdown files.\nMdformat is a Unix-style command-line tool as well as a Python library.\n\n<!-- end mini-description -->\n\nFind out more in the [docs](https://mdformat.readthedocs.io).\n\n<!-- start installing -->\n\n## Installing\n\nInstall with [CommonMark](https://spec.commonmark.org/current/) support:\n\n```bash\npip install mdformat\n```\n\nInstall with [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) support:\n\n```bash\npip install mdformat-gfm\n```\n\nNote that GitHub's Markdown renderer supports syntax extensions not included in the GFM specification.\nFor full GitHub support do:\n\n```bash\npip install mdformat-gfm mdformat-frontmatter mdformat-footnote\n```\n\nInstall with [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) support:\n\n```bash\npip install mdformat-myst\n```\n\n<!-- end installing -->\n\n<!-- start cli-usage -->\n\n## Command line usage\n\n### Format files\n\nFormat files `README.md` and `CHANGELOG.md` in place\n\n```bash\nmdformat README.md CHANGELOG.md\n```\n\nFormat `.md` files in current working directory recursively\n\n```bash\nmdformat .\n```\n\nRead Markdown from standard input until `EOF`.\nWrite formatted Markdown to standard output.\n\n```bash\nmdformat -\n```\n\n### Check formatting\n\n```bash\nmdformat --check README.md CHANGELOG.md\n```\n\nThis will not apply any changes to the files.\nIf a file is not properly formatted, the exit code will be non-zero.\n\n### Options\n\n```console\nfoo@bar:~$ mdformat --help\nusage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]\n\nCommonMark compliant Markdown formatter\n\npositional arguments:\n paths files to format\n\noptions:\n -h, --help show this help message and exit\n --check do not apply changes to files\n --version show program's version number and exit\n --number apply consecutive numbering to ordered lists\n --wrap {keep,no,INTEGER}\n paragraph word wrap mode (default: keep)\n --end-of-line {lf,crlf,keep}\n output file line ending mode (default: lf)\n```\n\n<!-- end cli-usage -->\n\n## Documentation\n\nThis README merely provides a quickstart guide for the command line interface.\nFor more information refer to the [documentation](https://mdformat.readthedocs.io).\nHere's a few pointers to get you started:\n\n- [Style guide](https://mdformat.readthedocs.io/en/stable/users/style.html)\n- [Python API usage](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#python-api-usage)\n- [Usage as a pre-commit hook](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook)\n- [Plugin usage](https://mdformat.readthedocs.io/en/stable/users/plugins.html)\n- [Plugin development guide](https://mdformat.readthedocs.io/en/stable/contributors/contributing.html)\n- [List of code block formatter plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#existing-plugins)\n- [List of parser extension plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#id1)\n- [Changelog](https://mdformat.readthedocs.io/en/stable/users/changelog.html)\n\n<!-- start faq -->\n\n## Frequently Asked Questions\n\n### Why not use [Prettier](https://github.com/prettier/prettier) instead?\n\nMdformat is pure Python code!\nPython is pre-installed on macOS and virtually any Linux distribution,\nmeaning that typically little to no additional installations are required to run mdformat.\nThis argument also holds true when using together with\n[pre-commit](https://github.com/pre-commit/pre-commit) (also Python).\nPrettier on the other hand requires Node.js/npm.\n\nPrettier suffers from\n[numerous](https://github.com/prettier/prettier/issues?q=is%3Aopen+label%3Alang%3Amarkdown+label%3Atype%3Abug+)\nbugs,\nmany of which cause changes in Markdown AST and rendered HTML.\nMany of these bugs are a consequence of using\n[`remark-parse`](https://github.com/remarkjs/remark/tree/main/packages/remark-parse)\nv8.x as Markdown parser which,\naccording to the author themselves,\nis [inferior to markdown-it](https://github.com/remarkjs/remark/issues/75#issuecomment-143532326) used by mdformat.\n`remark-parse` v9.x is advertised as CommonMark compliant\nand presumably would fix many of the issues,\nbut is not used by Prettier (v2.4.0) yet.\n\nPrettier (v2.4.0), being able to format many languages other than Markdown,\nis a large package with 65 direct dependencies\n(mdformat only has one in Python 3.11+).\nThis can be a disadvantage in many environments,\none example being size optimized Docker images.\n\nMdformat's parser extension plugin API allows not only customization of the Markdown specification in use,\nbut also advanced features like [automatic table of contents generation](https://github.com/hukkin/mdformat-toc).\nAlso provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.\n\n### What's wrong with the mdformat logo? It renders incorrectly and is just terrible in general.\n\nNope, the logo is actually pretty great \u2013 you're terrible.\nThe logo is more a piece of art than a logo anyways,\ndepicting the horrors of poorly formatted text documents.\nI made it myself!\n\nThat said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome \ud83d\ude04.\n\n<!-- end faq -->\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2021 Taneli Hukkinen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "CommonMark compliant Markdown formatter",
"version": "0.7.17",
"project_urls": {
"Changelog": "https://mdformat.readthedocs.io/en/stable/users/changelog.html",
"Documentation": "https://mdformat.readthedocs.io",
"Homepage": "https://github.com/executablebooks/mdformat",
"Style guide": "https://mdformat.readthedocs.io/en/stable/users/style.html"
},
"split_keywords": [
"mdformat",
"markdown",
"commonmark",
"formatter",
"pre-commit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bfd94790d04eb7bcc77f02000232b75e8356c5443ee9f6fe28a7786de96485c0",
"md5": "15f516e3be397a9098f361437ba98495",
"sha256": "91ffc5e203f5814a6ad17515c77767fd2737fc12ffd8b58b7bb1d8b9aa6effaa"
},
"downloads": -1,
"filename": "mdformat-0.7.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15f516e3be397a9098f361437ba98495",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28910,
"upload_time": "2023-08-25T10:12:28",
"upload_time_iso_8601": "2023-08-25T10:12:28.486292Z",
"url": "https://files.pythonhosted.org/packages/bf/d9/4790d04eb7bcc77f02000232b75e8356c5443ee9f6fe28a7786de96485c0/mdformat-0.7.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df866374cc48a89862cfc8e350a65d6af47792e83e7684f13e1222afce110a41",
"md5": "5266ef989d72ea01e9c563e82b841cb5",
"sha256": "a9dbb1838d43bb1e6f03bd5dca9412c552544a9bc42d6abb5dc32adfe8ae7c0d"
},
"downloads": -1,
"filename": "mdformat-0.7.17.tar.gz",
"has_sig": false,
"md5_digest": "5266ef989d72ea01e9c563e82b841cb5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36305,
"upload_time": "2023-08-25T10:12:30",
"upload_time_iso_8601": "2023-08-25T10:12:30.282048Z",
"url": "https://files.pythonhosted.org/packages/df/86/6374cc48a89862cfc8e350a65d6af47792e83e7684f13e1222afce110a41/mdformat-0.7.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-25 10:12:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "executablebooks",
"github_project": "mdformat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdformat"
}
