diff options
| author | Greg Roach <fisharebest@webtrees.net> | 2019-07-15 11:08:16 +0100 |
|---|---|---|
| committer | Greg Roach <fisharebest@webtrees.net> | 2019-07-16 10:52:40 +0100 |
| commit | 4a1f1d433794f86f893b59883147e57af4e94374 (patch) | |
| tree | 5cb9572b1be24c130a5b8a86b0e1672f822cdfc4 /vendor/league/commonmark/README.md | |
| parent | 22cfa91cf34e9677c2d99c712c2fc9e1c2c8f741 (diff) | |
| download | webtrees-4a1f1d433794f86f893b59883147e57af4e94374.tar.gz webtrees-4a1f1d433794f86f893b59883147e57af4e94374.tar.bz2 webtrees-4a1f1d433794f86f893b59883147e57af4e94374.zip | |
Package webuni/commonmark-table-extension is abandoned, you should avoid using it. Use league/commonmark-ext-table instead.
Diffstat (limited to 'vendor/league/commonmark/README.md')
| -rw-r--r-- | vendor/league/commonmark/README.md | 67 |
1 files changed, 16 insertions, 51 deletions
diff --git a/vendor/league/commonmark/README.md b/vendor/league/commonmark/README.md index 7bc6646f3b..06b238ea57 100644 --- a/vendor/league/commonmark/README.md +++ b/vendor/league/commonmark/README.md @@ -1,7 +1,5 @@ # league/commonmark -[](https://gitter.im/thephpleague/commonmark?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - [](https://packagist.org/packages/league/commonmark) [](https://packagist.org/packages/league/commonmark) [](LICENSE) @@ -45,54 +43,15 @@ echo $converter->convertToHtml('# Hello World!'); :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. -## Advanced Usage & Customization - -The actual conversion process requires two steps: - - 1. Parsing the Markdown input into an AST - 2. Rendering the AST document as HTML - -Although the `CommonMarkConverter` wrapper simplifies this process for you, advanced users will likely want to do this themselves: - -```php -use League\CommonMark\CommonMarkConverter; -use League\CommonMark\Environment; - -// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go -$environment = Environment::createCommonMarkEnvironment(); - -// Optional: Add your own parsers, renderers, extensions, etc. (if desired) -// For example: $environment->addInlineParser(new TwitterHandleParser()); - -// Define your configuration: -$config = ['html_input' => 'escape']; - -// Create the converter -$converter = new CommonMarkConverter($config, $environment); +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. -// Here's our sample input -$markdown = '# Hello World!'; - -// Let's render it! -echo $converter->convertToHtml($markdown); - -// The output should be: -// <h1>Hello World!</h1> -``` - -This approach allows you to access/modify the AST before rendering it. - -You can also add custom parsers/renderers by [registering them with the `Environment` class](https://commonmark.thephpleague.com/customization/environment/). -The [documentation][docs] provides several [customization examples][docs-examples] such as: - -- [Parsing Twitter handles into profile links][docs-example-twitter] -- [Converting smilies into emoticon images][docs-example-smilies] +## Documentation -You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you. +Full documentation on advanced usage, configuration, and customization can be found at [commonmark.thephpleague.com][docs]. -## Documentation +## Upgrading -Documentation can be found at [commonmark.thephpleague.com][docs]. +Information on how to upgrade to newer versions of this library can be found at <https://commonmark.thephpleague.com/releases>. ## Related Packages @@ -108,15 +67,21 @@ Documentation can be found at [commonmark.thephpleague.com][docs]. - [Twig-based renderer](https://github.com/webuni/commonmark-twig-renderer) - [Twig filter and tag](https://github.com/aptoma/twig-markdown) -### CommonMark Extras +### League Extensions + +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-inlines-only`](https://github.com/thephpleague/commonmark-ext-inlines-only) - Renders inline text without paragraph tags or other block-level elements -You can find several examples of useful extensions and customizations in the [league/commonmark-extras package](https://github.com/thephpleague/commonmark-extras). You can add them to your parser or use them as examples to [develop your own custom features](https://commonmark.thephpleague.com/customization/overview/). +You can add them to your project or use them as examples to [develop your own custom features](https://commonmark.thephpleague.com/customization/overview/). ### Community Extensions Custom parsers/renderers can be bundled into extensions which extend CommonMark. Here are some that you may find interesting: - - [Markua](https://github.com/dshafik/markua) - Markdown parser for PHP which intends to support the full Markua spec. - [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. @@ -133,14 +98,14 @@ Check out the other cool things people are doing with `league/commonmark`: <http 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.15.5 and higher supports version 0.28 of the [CommonMark spec]. +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 ``` bash -$ ./vendor/bin/phpunit +$ composer test ``` This will also test league/commonmark against the latest supported spec. |
