PyMarkdown

Project
Quality
Community
Maintainers

What Is PyMarkdown?

PyMarkdown is primarily a Markdown linter. To ensure that the Markdown linting 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 specification and the CommonMark 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, 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
• Portable
• Standardized
• Flexible
• Thoroughly tested
• 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 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
• a simple API layer

For more information on the Pymarkdown application and its command lines, please look here.

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, 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 and is kept up-to-date.