# PyMarkdown
| | |
|---|---|
|Project|[](https://pypi.org/project/pymarkdownlnt) [](https://pypi.org/project/pymarkdownlnt)  [](https://github.com/jackdewinter/pymarkdown/blob/main/LICENSE.txt) [](https://github.com/jackdewinter/pymarkdown)|
|Quality|[](https://github.com/jackdewinter/pymarkdown/actions/workflows/main.yml) [](https://github.com/jackdewinter/pymarkdown/issues) [](https://codecov.io/gh/jackdewinter/pymarkdown) [](https://sourcery.ai)  |
| |       |
|Community|[](https://github.com/jackdewinter/pymarkdown/graphs/commit-activity) [](https://github.com/jackdewinter/pymarkdown/stargazers) [](https://github.com/jackdewinter/pymarkdown/network/members) [](https://github.com/jackdewinter/pymarkdown/graphs/contributors) [](https://pypistats.org/packages/pymarkdownlnt)|
|Maintainers|[](https://www.linkedin.com/in/jackdewinter/)|
## What Is PyMarkdown?
PyMarkdown is primarily a Markdown linter. To ensure that the Markdown
[linting](https://en.wikipedia.org/wiki/Lint_%28software%29) is conducted with
the highest attention to detail, our linting rules analyze the tokens produced
by the project's own Markdown parser. The project's Markdown parser aims to be
highly compliant to both the
[GitHub Flavored Markdown](https://github.github.com/gfm/) specification and the
[CommonMark](https://spec.commonmark.org/) specification. This is important as
we estimate that over 90% of the existing parsers are mostly compliant to one of
those two specifications. By our parser adhering to those specifications, we
have a high degree of confidence that the rules we have written are based on
solid information about the structure of the Markdown documents that they are
evaluating. Since the rules have precise information on how compliant parsers
view the structure of a given Markdown document, each rule can make the best
decision possible on whether it should trigger a failure or not.
## Why Should I Use PyMarkdown?
We go into this in more detail in our [project documentation](https://pymarkdown.readthedocs.io/en/latest/),
but here is the short version.
Do you use spell checkers and grammer checkers for your emails, instant messages,
and documents?
Do you use static code analysis tools to verify that you are committing your best
source code to your projects?
Do you want to be able to customize your guidelines on a per-project basis with
little effort?
If the answer to any of those questions is "Yes", then we encourage you to
consider using our PyMarkdown linter to check you Markdown documents against
a configurable set of rules that you specify. We start you off with a common
set of rules and configuration settings, but you are able to enable, disable,
and configure rules to correspond to what you want the Markdown guidelines
to be for your project.
## What Advantages Does PyMarkdown Have Over Other Markdown Linters?
The PyMarkdown project has the following advantages:
- [Consistency](https://pymarkdown.readthedocs.io/en/latest/#consistency)
- [Portable](https://pymarkdown.readthedocs.io/en/latest/#portable)
- [Standardized](https://pymarkdown.readthedocs.io/en/latest/#standardized)
- [Flexible](https://pymarkdown.readthedocs.io/en/latest/#flexible)
- [Thoroughly tested](https://pymarkdown.readthedocs.io/en/latest/#thoroughly-tested)
- [Extensible](https://pymarkdown.readthedocs.io/en/latest/#extensible)
## What Are The Minimum Requirements?
This project required Python 3.8 or later to function.
## What Linting Checks Does PyMarkdown Release With?
The PyMarkdown project is released with 46 out-of-the-box rules to check your
Markdown with. Roughly 44 of those rules are our version of the rules provided
by the [Markdown Lint](https://github.com/markdownlint/markdownlint) project.
We purposefully made the decision to implement those rules as they are somewhat
of a standard due to Markdown Lint being a plugin for VSCode.
The reason that we state "our version of the rules" is because we believe that
some of the rules are either overly complicated or were not catching all use
cases properly. Our philosophy is that each Plugin Rule should perform one
check and one check only... no side-effect checks. We also believe that some
of the Markdown Lint rules do not understand the context of the document properly,
leading to misses for their rules. Our architecture was created to ensure that
we always have access to the context of any Markdown element that was scanned.
Basically, we want to support the worldwide users of Markdown by enabling
PyMarkdown to have the best rules possible. And to do this on the behalf of
our users, we feel that we need to make our own decisions on what a rule is.
## How Do I Run This Tool?
The PyMarkdown application is primarily a command line tool for linting, so
many features boil down to expressing them in the form of commands.
However, we also expose the following other ways to execute the PyMarkdown application:
- easy-to-use built-in hooks for [Pre-Commit](https://pymarkdown.readthedocs.io/en/latest/getting-started/#installing-via-pre-commit)
- a simple [API layer](https://pymarkdown.readthedocs.io/en/latest/api/)
For more information on the Pymarkdown application and its command lines,
please [look here](https://pymarkdown.readthedocs.io/en/latest/).
## What If It Is Missing A Feature That I Am Looking For?
Our project team is very open to discussing any features that you would like to
see in this project. The two most frequent requests we get are to extend our Markdown
parser to include a new extension or to extend our our Rule Engine to support
a new rule or a variation of an existing rule.
Extending our Markdown parser to accomodate widely supported Markdown elements
is one of the goals of our project. However, implementing an extension takes time,
especially when it comes to testing the extension. When we start working on an
extension, we usually forecast a 1-3 month window for the extension, with subreleases
along the way for people to try out.
Extending our Rule Engine to support new rules is built in to the foundation of
the Rule Engine itself with our Rule Plugins. Most of the time, we are able to
work on those in parallel
with other work and other testing, so that helps out as well. But they still take
time. With the addition of our new [Fix Mode](https://pymarkdown.readthedocs.io/en/latest/user-guide/#fix-mode-failure-correction),
adding the ability to automatically fix any issues takes even longer to complete
properly.
Neither of the last two paragraphs should be considered negative in the least.
We are just trying to explain that new features take time and why they take
time. The good news is that we are in the process of documenting the Rule Plugin
creation
process to the point where other people can work on them and submit them for consideration.
Look out for that in the near future!
## Where Can I Find More Detailed Information About PyMarkdown?
Our documentation is hosted at [ReadTheDocs](https://pymarkdown.readthedocs.io/en/latest/)
and is kept up-to-date.
Raw data
{
"_id": null,
"home_page": "https://github.com/jackdewinter/pymarkdown",
"name": "pymarkdownlnt",
"maintainer": "Jack De Winter",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "jack.de.winter@outlook.com",
"keywords": "markdown, linter, markdown linter",
"author": "Jack De Winter",
"author_email": "jack.de.winter@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/09/79/e991d2d0e67001fa83f0fc117cf35961e3637a4571218eff60f3b56b3863/pymarkdownlnt-0.9.19.tar.gz",
"platform": null,
"description": "# PyMarkdown\r\n\r\n| | |\r\n|---|---|\r\n|Project|[](https://pypi.org/project/pymarkdownlnt) [](https://pypi.org/project/pymarkdownlnt)  [](https://github.com/jackdewinter/pymarkdown/blob/main/LICENSE.txt) [](https://github.com/jackdewinter/pymarkdown)|\r\n|Quality|[](https://github.com/jackdewinter/pymarkdown/actions/workflows/main.yml) [](https://github.com/jackdewinter/pymarkdown/issues) [](https://codecov.io/gh/jackdewinter/pymarkdown) [](https://sourcery.ai)  |\r\n| |       |\r\n|Community|[](https://github.com/jackdewinter/pymarkdown/graphs/commit-activity) [](https://github.com/jackdewinter/pymarkdown/stargazers) [](https://github.com/jackdewinter/pymarkdown/network/members) [](https://github.com/jackdewinter/pymarkdown/graphs/contributors) [](https://pypistats.org/packages/pymarkdownlnt)|\r\n|Maintainers|[](https://www.linkedin.com/in/jackdewinter/)|\r\n\r\n## What Is PyMarkdown?\r\n\r\nPyMarkdown is primarily a Markdown linter. To ensure that the Markdown\r\n[linting](https://en.wikipedia.org/wiki/Lint_%28software%29) is conducted with\r\nthe highest attention to detail, our linting rules analyze the tokens produced\r\nby the project's own Markdown parser. The project's Markdown parser aims to be\r\nhighly compliant to both the\r\n[GitHub Flavored Markdown](https://github.github.com/gfm/) specification and the\r\n[CommonMark](https://spec.commonmark.org/) specification. This is important as\r\nwe estimate that over 90% of the existing parsers are mostly compliant to one of\r\nthose two specifications. By our parser adhering to those specifications, we\r\nhave a high degree of confidence that the rules we have written are based on\r\nsolid information about the structure of the Markdown documents that they are\r\nevaluating. Since the rules have precise information on how compliant parsers\r\nview the structure of a given Markdown document, each rule can make the best\r\ndecision possible on whether it should trigger a failure or not.\r\n\r\n## Why Should I Use PyMarkdown?\r\n\r\nWe go into this in more detail in our [project documentation](https://pymarkdown.readthedocs.io/en/latest/),\r\nbut here is the short version.\r\n\r\nDo you use spell checkers and grammer checkers for your emails, instant messages,\r\nand documents?\r\n\r\nDo you use static code analysis tools to verify that you are committing your best\r\nsource code to your projects?\r\n\r\nDo you want to be able to customize your guidelines on a per-project basis with\r\nlittle effort?\r\n\r\nIf the answer to any of those questions is \"Yes\", then we encourage you to\r\nconsider using our PyMarkdown linter to check you Markdown documents against\r\na configurable set of rules that you specify. We start you off with a common\r\nset of rules and configuration settings, but you are able to enable, disable,\r\nand configure rules to correspond to what you want the Markdown guidelines\r\nto be for your project.\r\n\r\n## What Advantages Does PyMarkdown Have Over Other Markdown Linters?\r\n\r\nThe PyMarkdown project has the following advantages:\r\n\r\n- [Consistency](https://pymarkdown.readthedocs.io/en/latest/#consistency)\r\n- [Portable](https://pymarkdown.readthedocs.io/en/latest/#portable)\r\n- [Standardized](https://pymarkdown.readthedocs.io/en/latest/#standardized)\r\n- [Flexible](https://pymarkdown.readthedocs.io/en/latest/#flexible)\r\n- [Thoroughly tested](https://pymarkdown.readthedocs.io/en/latest/#thoroughly-tested)\r\n- [Extensible](https://pymarkdown.readthedocs.io/en/latest/#extensible)\r\n\r\n## What Are The Minimum Requirements?\r\n\r\nThis project required Python 3.8 or later to function.\r\n\r\n## What Linting Checks Does PyMarkdown Release With?\r\n\r\nThe PyMarkdown project is released with 46 out-of-the-box rules to check your\r\nMarkdown with. Roughly 44 of those rules are our version of the rules provided\r\nby the [Markdown Lint](https://github.com/markdownlint/markdownlint) project.\r\nWe purposefully made the decision to implement those rules as they are somewhat\r\nof a standard due to Markdown Lint being a plugin for VSCode.\r\n\r\nThe reason that we state \"our version of the rules\" is because we believe that\r\nsome of the rules are either overly complicated or were not catching all use\r\ncases properly. Our philosophy is that each Plugin Rule should perform one\r\ncheck and one check only... no side-effect checks. We also believe that some\r\nof the Markdown Lint rules do not understand the context of the document properly,\r\nleading to misses for their rules. Our architecture was created to ensure that\r\nwe always have access to the context of any Markdown element that was scanned.\r\n\r\nBasically, we want to support the worldwide users of Markdown by enabling\r\nPyMarkdown to have the best rules possible. And to do this on the behalf of\r\nour users, we feel that we need to make our own decisions on what a rule is.\r\n\r\n## How Do I Run This Tool?\r\n\r\nThe PyMarkdown application is primarily a command line tool for linting, so\r\nmany features boil down to expressing them in the form of commands.\r\n\r\nHowever, we also expose the following other ways to execute the PyMarkdown application:\r\n\r\n- easy-to-use built-in hooks for [Pre-Commit](https://pymarkdown.readthedocs.io/en/latest/getting-started/#installing-via-pre-commit)\r\n- a simple [API layer](https://pymarkdown.readthedocs.io/en/latest/api/)\r\n\r\nFor more information on the Pymarkdown application and its command lines,\r\nplease [look here](https://pymarkdown.readthedocs.io/en/latest/).\r\n\r\n## What If It Is Missing A Feature That I Am Looking For?\r\n\r\nOur project team is very open to discussing any features that you would like to\r\nsee in this project. The two most frequent requests we get are to extend our Markdown\r\nparser to include a new extension or to extend our our Rule Engine to support\r\na new rule or a variation of an existing rule.\r\n\r\nExtending our Markdown parser to accomodate widely supported Markdown elements\r\nis one of the goals of our project. However, implementing an extension takes time,\r\nespecially when it comes to testing the extension. When we start working on an\r\nextension, we usually forecast a 1-3 month window for the extension, with subreleases\r\nalong the way for people to try out.\r\n\r\nExtending our Rule Engine to support new rules is built in to the foundation of\r\nthe Rule Engine itself with our Rule Plugins. Most of the time, we are able to\r\nwork on those in parallel\r\nwith other work and other testing, so that helps out as well. But they still take\r\ntime. With the addition of our new [Fix Mode](https://pymarkdown.readthedocs.io/en/latest/user-guide/#fix-mode-failure-correction),\r\nadding the ability to automatically fix any issues takes even longer to complete\r\nproperly.\r\n\r\nNeither of the last two paragraphs should be considered negative in the least.\r\nWe are just trying to explain that new features take time and why they take\r\ntime. The good news is that we are in the process of documenting the Rule Plugin\r\ncreation\r\nprocess to the point where other people can work on them and submit them for consideration.\r\nLook out for that in the near future!\r\n\r\n## Where Can I Find More Detailed Information About PyMarkdown?\r\n\r\nOur documentation is hosted at [ReadTheDocs](https://pymarkdown.readthedocs.io/en/latest/)\r\nand is kept up-to-date.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A GitHub Flavored Markdown compliant Markdown linter.",
"version": "0.9.19",
"project_urls": {
"Change Log": "https://github.com/jackdewinter/pymarkdown/blob/main/changelog.md",
"Homepage": "https://github.com/jackdewinter/pymarkdown"
},
"split_keywords": [
"markdown",
" linter",
" markdown linter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f21eaa081d50feba660ed5a5c5cc218a0d5156403f322d80b434abc3fc449788",
"md5": "df4ccbccb3d551494dcc55113120a3cf",
"sha256": "f1584d1b559fef634f83bdfb004b9d446cccc14a8448d01ff66c67d5949e1b7d"
},
"downloads": -1,
"filename": "pymarkdownlnt-0.9.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df4ccbccb3d551494dcc55113120a3cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 438896,
"upload_time": "2024-05-01T03:13:24",
"upload_time_iso_8601": "2024-05-01T03:13:24.422556Z",
"url": "https://files.pythonhosted.org/packages/f2/1e/aa081d50feba660ed5a5c5cc218a0d5156403f322d80b434abc3fc449788/pymarkdownlnt-0.9.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0979e991d2d0e67001fa83f0fc117cf35961e3637a4571218eff60f3b56b3863",
"md5": "aaa554ff18c5c9d2d406d986b5791806",
"sha256": "4ef7b1a2b1ab67e6c5e8859d773f5367638158bd699869f8fbdfdf36d68359d8"
},
"downloads": -1,
"filename": "pymarkdownlnt-0.9.19.tar.gz",
"has_sig": false,
"md5_digest": "aaa554ff18c5c9d2d406d986b5791806",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 343493,
"upload_time": "2024-05-01T03:13:26",
"upload_time_iso_8601": "2024-05-01T03:13:26.303939Z",
"url": "https://files.pythonhosted.org/packages/09/79/e991d2d0e67001fa83f0fc117cf35961e3637a4571218eff60f3b56b3863/pymarkdownlnt-0.9.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 03:13:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jackdewinter",
"github_project": "pymarkdown",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pymarkdownlnt"
}
JSON
