diff options
Diffstat (limited to 'vendor/league/commonmark/README.md')
| -rw-r--r-- | vendor/league/commonmark/README.md | 119 |
1 files changed, 58 insertions, 61 deletions
diff --git a/vendor/league/commonmark/README.md b/vendor/league/commonmark/README.md index 06b238ea57..301b0103d1 100644 --- a/vendor/league/commonmark/README.md +++ b/vendor/league/commonmark/README.md @@ -6,19 +6,15 @@ [](https://travis-ci.org/thephpleague/commonmark) [](https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure) [](https://scrutinizer-ci.com/g/thephpleague/commonmark) -[](https://insight.sensiolabs.com/projects/9bf971c0-458f-4a19-9898-127728dbd65d) [](https://bestpractices.coreinfrastructure.org/projects/126) -**league/commonmark** is a PHP-based Markdown parser created by [Colin O'Dell][@colinodell] which supports the full [CommonMark] spec. It is based on the [CommonMark JS reference implementation][commonmark.js] by [John MacFarlane] \([@jgm]\). +[](https://www.patreon.com/colinodell) -## Goals + -* Fully support the CommonMark spec (100% compliance) -* Match the C and JavaScript implementations of CommonMark to make a logical and similar API -* Continuously improve performance without sacrificing quality or compliance -* Provide an extensible parser/renderer which users may customize as needed +**league/commonmark** is a highly-extensible PHP Markdown parser created by [Colin O'Dell][@colinodell] which supports the full [CommonMark] spec. It is based on the [CommonMark JS reference implementation][commonmark.js] by [John MacFarlane] \([@jgm]\). -## Installation +## ๐ฆ Installation & Basic Usage This project can be installed via [Composer]: @@ -26,34 +22,34 @@ This project can be installed via [Composer]: $ composer require league/commonmark ``` -**Note:** See [Versioning](#versioning) for important information on which version constraints you should use. - -## Basic Usage - The `CommonMarkConverter` class provides a simple wrapper for converting CommonMark to HTML: ```php use League\CommonMark\CommonMarkConverter; -$converter = new CommonMarkConverter(); +$converter = new CommonMarkConverter([ + 'html_input' => 'strip', + 'allow_unsafe_links' => false, +]); + echo $converter->convertToHtml('# Hello World!'); // <h1>Hello World!</h1> ``` -:warning: **Security warning:** If you will be parsing untrusted input from users, please consider setting the `html_input` and `allow_unsafe_links` options. See <https://commonmark.thephpleague.com/security/> for more details. +Please note that only UTF-8 and ASCII encodings are supported. If your Markdown uses a different encoding please convert it to UTF-8 before running it through this library. -If you also do choose to allow raw HTML input from untrusted users, considering using a library (like [HTML Purifier](https://github.com/ezyang/htmlpurifier)) to provide additional HTML filtering. +๐ If you will be parsing untrusted input from users, please consider setting the `html_input` and `allow_unsafe_links` options per the example above. See <https://commonmark.thephpleague.com/security/> for more details. If you also do choose to allow raw HTML input from untrusted users, considering using a library (like [HTML Purifier](https://github.com/ezyang/htmlpurifier)) to provide additional HTML filtering. -## Documentation +## ๐ Documentation Full documentation on advanced usage, configuration, and customization can be found at [commonmark.thephpleague.com][docs]. -## Upgrading +## โซ Upgrading Information on how to upgrade to newer versions of this library can be found at <https://commonmark.thephpleague.com/releases>. -## Related Packages +## ๐๏ธ Related Packages ### Integrations @@ -64,7 +60,6 @@ Information on how to upgrade to newer versions of this library can be found at - [Symfony 2 & 3](https://github.com/webuni/commonmark-bundle) - [Symfony 4](https://github.com/avensome/commonmark-bundle) - [Twig Markdown extension](https://github.com/twigphp/markdown-extension) -- [Twig-based renderer](https://github.com/webuni/commonmark-twig-renderer) - [Twig filter and tag](https://github.com/aptoma/twig-markdown) ### League Extensions @@ -74,7 +69,10 @@ The PHP League offers useful extensions that add extra syntax and features: - [`league/commonmark-extras`](https://github.com/thephpleague/commonmark-extras) - Bundles the extensions below into a single dependency for convenience - [`league/commonmark-ext-autolink`](https://github.com/thephpleague/commonmark-ext-autolink) - Extension for league/commonmark which autolinks URLs, emails, and (optionally) @-mentions - [`league/commonmark-ext-smartpunct`](https://github.com/thephpleague/commonmark-ext-smartpunct) - Intelligently converts ASCII quotes, dashes, and ellipses to their Unicode equivalents + - [`league/commonmark-ext-strikethrough`](https://github.com/thephpleague/commonmark-ext-strikethrough) - Adds support for `~~strikethrough~~` syntax + - [`league/commonmark-ext-task-list`](https://github.com/thephpleague/commonmark-ext-task-list) - Support for Github-style task lists - [`league/commonmark-ext-inlines-only`](https://github.com/thephpleague/commonmark-ext-inlines-only) - Renders inline text without paragraph tags or other block-level elements + - [`league/commonmark-ext-external-link`](https://github.com/thephpleague/commonmark-ext-external-link) - Mark external links, make them open in new windows, etc. You can add them to your project or use them as examples to [develop your own custom features](https://commonmark.thephpleague.com/customization/overview/). @@ -85,86 +83,85 @@ Custom parsers/renderers can be bundled into extensions which extend CommonMark. - [CommonMark Table Extension](https://github.com/webuni/commonmark-table-extension) - Adds the ability to create tables in CommonMark documents. - [CommonMark Attributes Extension](https://github.com/webuni/commonmark-attributes-extension) - Adds a syntax to define attributes on the various HTML elements. - [Alt Three Emoji](https://github.com/AltThree/Emoji) An emoji parser for CommonMark. - - [uafrica/commonmark-ext](https://github.com/uafrica/commonmark-ext) - Adds strikethrough support. - [Sup Sub extensions](https://github.com/OWS/commonmark-sup-sub-extensions) - Adds support of superscript and subscript (`<sup>` and `<sub>` HTML tags) +Others can be found on [Packagist under the `commonmark-extension` package type](https://packagist.org/packages/league/commonmark?type=commonmark-extension). + If you build your own, feel free to submit a PR to add it to this list! ### Others Check out the other cool things people are doing with `league/commonmark`: <https://packagist.org/packages/league/commonmark/dependents> -## Compatibility with CommonMark ## - -This project aims to fully support the entire [CommonMark spec]. Other flavors of Markdown may work but are not supported. Any/all changes made to the [spec][CommonMark spec] or [JS reference implementation][commonmark.js] should eventually find their way back into this codebase. - -league/commonmark 0.19.0 and higher supports version 0.29 of the [CommonMark spec]. - -(This package is **not** part of CommonMark, but rather a compatible derivative.) - -## Testing +## ๐ท๏ธ Versioning -``` bash -$ composer test -``` - -This will also test league/commonmark against the latest supported spec. +[SemVer](http://semver.org/) is followed closely. Minor and patch releases should not introduce breaking changes to the codebase; however, they might change the resulting AST or HTML output of parsed Markdown (due to bug fixes, spec changes, etc.) As a result, you might get slightly different HTML, but any custom code built onto this library should still function correctly. -## Performance Benchmarks +Any classes or methods marked `@internal` are not intended for use outside of this library and are subject to breaking changes at any time, so please avoid using them. -You can compare the performance of **league/commonmark** to other popular parsers by running the included benchmark tool: +## ๐ ๏ธ Maintenance & Support -``` bash -$ ./tests/benchmark/benchmark.php -``` +When a new **minor** version (`1.x`) is released, the previous one will continue to receive security and bug fixes for *at least* 3 months. -## Versioning +When a new **major** version is released (`1.0`, `2.0`, etc), the previous one (`0.19.x`) will receive bug fixes for *at least* 3 months and security updates for 6 months after that new release comes out. -[SemVer](http://semver.org/) will be followed closely. 0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. **It's highly recommended that you use [Composer's caret operator](https://getcomposer.org/doc/articles/versions.md#caret) to ensure compatibility**; for example: `^0.18`. This is equivalent to `>=0.18.0 <0.19.0`. +(This policy may change in the future and exceptions may be made on a case-by-case basis.) -0.x.y releases should not introduce breaking changes to the codebase; however, they might change the resulting AST or HTML output of parsed Markdown (due to bug fixes, minor spec changes, etc.) As a result, you might get slightly different HTML, but any custom code built onto this library will still function correctly. +## ๐ทโโ๏ธ Contributing -If you're only using the `CommonMarkConverter` class or `ConverterInterface` to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like `~0.18`, `>0.18`, etc. I personally promise to never break this specific class in any future 0.x release. +To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure with us. -## Stability +If you encounter a bug in the spec, please report it to the [CommonMark] project. Any resulting fix will eventually be implemented in this project as well. -While this package does work well, the underlying code should not be considered "stable" yet. The original spec and JS parser may undergo changes in the near future which will result in corresponding changes to this code. Any methods tagged with `@api` are not expected to change, but other methods/classes might. +Contributions to this library are **welcome**, especially ones that: -Major release 1.0.0 will be reserved for when either the CommonMark spec or this project are considered stable (see [outstanding CommonMark spec issues](http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287)). 0.x.y will be used until that happens. + * Improve usability or flexibility without compromising our ability to adhere to the [CommonMark spec] + * Mirror fixes made to the [reference implementation][commonmark.js] + * Optimize performance + * Fix issues with adhering to the [CommonMark spec] -## Contributing +Major refactoring to core parsing logic should be avoided if possible so that we can easily follow updates made to [the reference implementation][commonmark.js]. That being said, we will absolutely consider changes which don't deviate too far from the reference spec or which are favored by other popular CommonMark implementations. -If you encounter a bug in the spec, please report it to the [CommonMark] project. Any resulting fix will eventually be implemented in this project as well. +Please see [CONTRIBUTING](https://github.com/thephpleague/commonmark/blob/master/.github/CONTRIBUTING.md) for additional details. -For now, I'd like to maintain similar logic as the [JS reference implementation][commonmark.js] until everything is stable. I'll gladly accept any contributions which: +## ๐งช Testing - * Mirror fixes made to the [reference implementation][commonmark.js] - * Optimize existing methods or regular expressions - * Fix issues with adhering to the spec examples +``` bash +$ composer test +``` -Major refactoring should be avoided for now so that we can easily follow updates made to [the reference implementation][commonmark.js]. This restriction will likely be lifted once the CommonMark specs and implementations are considered stable. +This will also test league/commonmark against the latest supported spec. -Please see [CONTRIBUTING](https://github.com/thephpleague/commonmark/blob/master/CONTRIBUTING.md) for additional details. +## ๐ Performance Benchmarks -## Security +You can compare the performance of **league/commonmark** to other popular parsers by running the included benchmark tool: -If you discover any security related issues, please email your report privately to colinodell@gmail.com instead of using the issue tracker. +``` bash +$ ./tests/benchmark/benchmark.php +``` -## Credits & Acknowledgements +## ๐ฅ Credits & Acknowledgements - [Colin O'Dell][@colinodell] - [John MacFarlane][@jgm] - [All Contributors] -This code is a port of the [CommonMark JS reference implementation][commonmark.js] which is written, maintained and copyrighted by [John MacFarlane]. This project simply wouldn't exist without his work. +This code is partially based on the [CommonMark JS reference implementation][commonmark.js] which is written, maintained and copyrighted by [John MacFarlane]. This project simply wouldn't exist without his work. + +### Sponsors + +We'd also like to extend our sincere thanks the following sponsors who support ongoing development of this project: + + - [RIPS Technologies](https://www.ripstech.com/) for supporting this project with a complimentary [RIPS SaaS](https://www.ripstech.com/product/) license + - [JetBrains](https://www.jetbrains.com/) for supporting this project with complimentary [PhpStorm](https://www.jetbrains.com/phpstorm/) licenses -Also a huge thank you to [JetBrains](https://www.jetbrains.com/) for supporting the development of this project with complimentary [PhpStorm](https://www.jetbrains.com/phpstorm/) licenses. +Are you interested in sponsoring development of this project? [Make a pledge](https://www.patreon.com/join/colinodell) of $10 or more and we'll include your name [on our website](https://commonmark.thephpleague.com/#sponsors)! -## License ## +## ๐ License **league/commonmark** is licensed under the BSD-3 license. See the [`LICENSE`](LICENSE) file for more details. -## Governance +## ๐๏ธ Governance This project is primarily maintained by [Colin O'Dell][@colinodell]. Members of the [PHP League] Leadership Team may occasionally assist with some of these duties. |