From 29060da9f8f7889149d1c34c9637ab7cc0393d42 Mon Sep 17 00:00:00 2001 From: Alexey Pyltsyn Date: Fri, 4 Oct 2019 15:59:27 +0300 Subject: [PATCH] Improve docs --- docs/0.18/customization/inline-rendering.md | 2 +- docs/0.18/installation.md | 2 +- docs/0.18/upgrading.md | 2 +- docs/0.19/customization/inline-rendering.md | 2 +- docs/0.19/installation.md | 2 +- docs/0.19/upgrading.md | 2 +- docs/1.0/configuration.md | 2 +- docs/1.0/customization/event-dispatcher.md | 2 +- docs/1.0/customization/inline-parsing.md | 2 +- docs/1.0/customization/inline-rendering.md | 2 +- docs/1.0/installation.md | 2 +- docs/1.0/security.md | 1 + 12 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/0.18/customization/inline-rendering.md b/docs/0.18/customization/inline-rendering.md index 7f5dfe6280..8cf7d25a65 100644 --- a/docs/0.18/customization/inline-rendering.md +++ b/docs/0.18/customization/inline-rendering.md @@ -23,7 +23,7 @@ If the method can only handle certain inline types, be sure to verify that you'v ### Return value -The method must return the final HTML represenation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. +The method must return the final HTML representation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. You are responsible for handling any escaping that may be necessary. diff --git a/docs/0.18/installation.md b/docs/0.18/installation.md index daeb297fda..4aaf194e19 100644 --- a/docs/0.18/installation.md +++ b/docs/0.18/installation.md @@ -17,6 +17,6 @@ Ensure that you’ve set up your project to [autoload Composer-installed package ## Versioning -[SemVer](http://semver.org/) will be followed closely. 0.x versions will introduce breaking changes, 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 compatiblity**; for example: `^0.18`. This is equivalent to `>=0.18.0 <0.19.0`. +[SemVer](http://semver.org/) will be followed closely. 0.x versions will introduce breaking changes, 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`. If you're only using the `CommonMarkConverter` class 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. diff --git a/docs/0.18/upgrading.md b/docs/0.18/upgrading.md index ccf825a2d0..42f2324ac8 100644 --- a/docs/0.18/upgrading.md +++ b/docs/0.18/upgrading.md @@ -5,4 +5,4 @@ title: Upgrading from 0.17 to 0.18 # Upgrading from 0.17 to 0.18 -No breaking changes were introduced, but we did add a new interface: `ConverterInface`. Consider depending on this interface in your code instead of the concrete implementation. (See [#330](https://github.com/thephpleague/commonmark/issues/330)) \ No newline at end of file +No breaking changes were introduced, but we did add a new interface: `ConverterInterface`. Consider depending on this interface in your code instead of the concrete implementation. (See [#330](https://github.com/thephpleague/commonmark/issues/330)) \ No newline at end of file diff --git a/docs/0.19/customization/inline-rendering.md b/docs/0.19/customization/inline-rendering.md index 1c7b8aaf19..2983cd5342 100644 --- a/docs/0.19/customization/inline-rendering.md +++ b/docs/0.19/customization/inline-rendering.md @@ -24,7 +24,7 @@ If the method can only handle certain inline types, be sure to verify that you'v ### Return value -The method must return the final HTML represenation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. +The method must return the final HTML representation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. You are responsible for handling any escaping that may be necessary. diff --git a/docs/0.19/installation.md b/docs/0.19/installation.md index 5b21298f9b..2287271e71 100644 --- a/docs/0.19/installation.md +++ b/docs/0.19/installation.md @@ -18,6 +18,6 @@ Ensure that you’ve set up your project to [autoload Composer-installed package ## Versioning -[SemVer](http://semver.org/) will be followed closely. 0.x versions will introduce breaking changes, 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 compatiblity**; for example: `^0.18`. This is equivalent to `>=0.18.0 <0.19.0`. +[SemVer](http://semver.org/) will be followed closely. 0.x versions will introduce breaking changes, 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`. If you're only using the `CommonMarkConverter` class to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like `~0.19`, `>0.19`, etc. I personally promise to never break this specific class in any future 0.x release. diff --git a/docs/0.19/upgrading.md b/docs/0.19/upgrading.md index b13417ae21..753bf1c228 100644 --- a/docs/0.19/upgrading.md +++ b/docs/0.19/upgrading.md @@ -26,7 +26,7 @@ The `getName()` method has been removed from several classes: This method was originally intended for supporting XML rendering, which was never implemented, and will likely define names a bit differently if/when we do add support. -After doing this, the two abstract classes mentioned above had notthing left in them, so those were removed. Any parsers previously extending them should directly implement the corresponding interface instead. +After doing this, the two abstract classes mentioned above had nothing left in them, so those were removed. Any parsers previously extending them should directly implement the corresponding interface instead. `InlineContainer` was also removed. diff --git a/docs/1.0/configuration.md b/docs/1.0/configuration.md index 2222adb011..5b9aedea61 100644 --- a/docs/1.0/configuration.md +++ b/docs/1.0/configuration.md @@ -26,7 +26,7 @@ $converter = new CommonMarkConverter([ 'use_underscore' => true, 'html_input' => 'escape', 'allow_unsafe_links' => false, - 'max_nesting_level' => INF + 'max_nesting_level' => INF, ]); ~~~ diff --git a/docs/1.0/customization/event-dispatcher.md b/docs/1.0/customization/event-dispatcher.md index ff01775ec2..4fb24fd3e9 100644 --- a/docs/1.0/customization/event-dispatcher.md +++ b/docs/1.0/customization/event-dispatcher.md @@ -1,7 +1,7 @@ --- layout: default title: Event Dispatcher -description: How to leverate the event dispatcher to hook into the library +description: How to leverage the event dispatcher to hook into the library redirect_from: - /0.20/customization/document-processing/ - /1.0/customization/document-processing/ diff --git a/docs/1.0/customization/inline-parsing.md b/docs/1.0/customization/inline-parsing.md index e52eeffbf6..affc4cc708 100644 --- a/docs/1.0/customization/inline-parsing.md +++ b/docs/1.0/customization/inline-parsing.md @@ -144,6 +144,6 @@ $environment->addInlineParser(new SmilieParserParser()); ## Tips -* For best performance, `return false` **as soon as possible** +* For best performance, `return false` **as soon as possible**. * You can `peek()` without modifying the cursor state. This makes it useful for validating nearby characters as it's quick and you can bail without needed to restore state. * You can look at (and modify) any part of the AST if needed (via `$inlineContext->getContainer()`). diff --git a/docs/1.0/customization/inline-rendering.md b/docs/1.0/customization/inline-rendering.md index c5e9c4ce14..9941b53cf5 100644 --- a/docs/1.0/customization/inline-rendering.md +++ b/docs/1.0/customization/inline-rendering.md @@ -25,7 +25,7 @@ If the method can only handle certain inline types, be sure to verify that you'v ### Return value -The method must return the final HTML represenation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. +The method must return the final HTML representation of the entire inline and any contents. This can be an `HtmlElement` object (preferred; castable to a string) or a string of raw HTML. You are responsible for handling any escaping that may be necessary. diff --git a/docs/1.0/installation.md b/docs/1.0/installation.md index cb65bd6481..aee7ca6ec6 100644 --- a/docs/1.0/installation.md +++ b/docs/1.0/installation.md @@ -19,4 +19,4 @@ Ensure that you’ve set up your project to [autoload Composer-installed package ## Versioning -[SemVer](http://semver.org/) will be followed closely. **It's highly recommended that you use [Composer's caret operator](https://getcomposer.org/doc/articles/versions.md#caret) to ensure compatiblity**; for example: `^1.0`. This is equivalent to `>=1.0 <2.0`. +[SemVer](http://semver.org/) will be followed closely. **It's highly recommended that you use [Composer's caret operator](https://getcomposer.org/doc/articles/versions.md#caret) to ensure compatibility**; for example: `^1.0`. This is equivalent to `>=1.0 <2.0`. diff --git a/docs/1.0/security.md b/docs/1.0/security.md index bc1a8ab26b..eb70952a4e 100644 --- a/docs/1.0/security.md +++ b/docs/1.0/security.md @@ -57,6 +57,7 @@ To prevent these from being parsed and rendered, you should set the `allow_unsaf If you need to parse untrusted input, consider setting a reasonable `max_nesting_level` (perhaps 10-50) depending on your needs. Once this nesting level is hit, any subsequent Markdown will be rendered as plain text. ### Example - Prevent deep nesting + ~~~php use League\CommonMark\CommonMarkConverter;