Skip to content

Commit

Permalink
Fix doc version issues
Browse files Browse the repository at this point in the history
  • Loading branch information
colinodell committed Dec 10, 2024
1 parent b561666 commit 88365ec
Show file tree
Hide file tree
Showing 5 changed files with 26 additions and 26 deletions.
2 changes: 0 additions & 2 deletions docs/2.5/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ $config = [
'html_input' => 'escape',
'allow_unsafe_links' => false,
'max_nesting_level' => PHP_INT_MAX,
'max_delimiters_per_line' => PHP_INT_MAX,
'slug_normalizer' => [
'max_length' => 255,
],
Expand Down Expand Up @@ -73,7 +72,6 @@ Here's a list of the core configuration options available:
- `escape` - Escape all HTML
- `allow_unsafe_links` - Remove risky link and image URLs by setting this to `false` (default: `true`)
- `max_nesting_level` - The maximum nesting level for blocks (default: `PHP_INT_MAX`). Setting this to a positive integer can help protect against long parse times and/or segfaults if blocks are too deeply-nested.
- `max_delimiters_per_line` - The maximum number of delimiters (e.g. `*` or `_`) allowed in a single line (default: `PHP_INT_MAX`). Setting this to a positive integer can help protect against long parse times and/or segfaults if lines are too long.
- `slug_normalizer` - Array of options for configuring how URL-safe slugs are created; see [the slug normalizer docs](/2.5/customization/slug-normalizer/#configuration) for more details
- `instance` - An alternative normalizer to use (defaults to the included `SlugNormalizer`)
- `max_length` - Limits the size of generated slugs (defaults to 255 characters)
Expand Down
20 changes: 0 additions & 20 deletions docs/2.5/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ In order to be fully compliant with the CommonMark spec, certain security settin
- `html_input`: How to handle raw HTML
- `allow_unsafe_links`: Whether unsafe links are permitted
- `max_nesting_level`: Protect against long render times or segfaults
- `max_delimiters_per_line`: Protect against long parse times or rendering segfaults

Further information about each option can be found below.

Expand Down Expand Up @@ -88,25 +87,6 @@ echo $converter->convert($markdown);

See the [configuration](/2.5/configuration/) section for more information.

## Max Delimiters Per Line

Similarly to the maximum nesting level, **no maximum number of delimiters per line is enforced by default.** Delimiters can be nested (like `*a **b** c*`) or un-nested (like `*a* *b* *c*`) - in either case, having too many in a single line can result in long parse times. We therefore have a separate option to limit the number of delimiters per line.

If you need to parse untrusted input, consider setting a reasonable `max_delimiters_per_line` (perhaps 100-1000) depending on your needs. Once this level is hit, any subsequent delimiters on that line will be rendered as plain text.

### Example - Prevent too many delimiters

```php
use League\CommonMark\CommonMarkConverter;

$markdown = '*a* **b *c **d** c* b**'; // 8 delimiters (* and **)

$converter = new CommonMarkConverter(['max_delimiters_per_line' => 6]);
echo $converter->convert($markdown);

// <p><em>a</em> **b *c <strong>d</strong> c* b**</p>
```

## Additional Filtering

Although this library does offer these security features out-of-the-box, some users may opt to also run the HTML output through additional filtering layers (like HTMLPurifier). If you do this, make sure you **thoroughly** test your additional post-processing steps and configure them to work properly with the types of HTML elements and attributes that converted Markdown might produce, otherwise, you may end up with weird behavior like missing images, broken links, mismatched HTML tags, etc.
4 changes: 3 additions & 1 deletion docs/2.6/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ $config = [
'html_input' => 'escape',
'allow_unsafe_links' => false,
'max_nesting_level' => PHP_INT_MAX,
'max_delimiters_per_line' => PHP_INT_MAX,
'slug_normalizer' => [
'max_length' => 255,
],
Expand Down Expand Up @@ -73,7 +74,8 @@ Here's a list of the core configuration options available:
- `escape` - Escape all HTML
- `allow_unsafe_links` - Remove risky link and image URLs by setting this to `false` (default: `true`)
- `max_nesting_level` - The maximum nesting level for blocks (default: `PHP_INT_MAX`). Setting this to a positive integer can help protect against long parse times and/or segfaults if blocks are too deeply-nested.
- `slug_normalizer` - Array of options for configuring how URL-safe slugs are created; see [the slug normalizer docs](/2.6/customization/slug-normalizer/#configuration) for more details
- `max_delimiters_per_line` - The maximum number of delimiters (e.g. `*` or `_`) allowed in a single line (default: `PHP_INT_MAX`). Setting this to a positive integer can help protect against long parse times and/or segfaults if lines are too long.
- `slug_normalizer` - Array of options for configuring how URL-safe slugs are created; see [the slug normalizer docs](/2.5/customization/slug-normalizer/#configuration) for more details
- `instance` - An alternative normalizer to use (defaults to the included `SlugNormalizer`)
- `max_length` - Limits the size of generated slugs (defaults to 255 characters)
- `unique` - Controls whether slugs should be unique per `'document'` (default) or per `'environment'`; can be disabled with `false`
Expand Down
22 changes: 21 additions & 1 deletion docs/2.6/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ In order to be fully compliant with the CommonMark spec, certain security settin

- `html_input`: How to handle raw HTML
- `allow_unsafe_links`: Whether unsafe links are permitted
- `max_nesting_level`: Protected against long render times or segfaults
- `max_nesting_level`: Protect against long render times or segfaults
- `max_delimiters_per_line`: Protect against long parse times or rendering segfaults

Further information about each option can be found below.

Expand Down Expand Up @@ -88,6 +89,25 @@ echo $converter->convert($markdown);

See the [configuration](/2.6/configuration/) section for more information.

## Max Delimiters Per Line

Similarly to the maximum nesting level, **no maximum number of delimiters per line is enforced by default.** Delimiters can be nested (like `*a **b** c*`) or un-nested (like `*a* *b* *c*`) - in either case, having too many in a single line can result in long parse times. We therefore have a separate option to limit the number of delimiters per line.

If you need to parse untrusted input, consider setting a reasonable `max_delimiters_per_line` (perhaps 100-1000) depending on your needs. Once this level is hit, any subsequent delimiters on that line will be rendered as plain text.

### Example - Prevent too many delimiters

```php
use League\CommonMark\CommonMarkConverter;

$markdown = '*a* **b *c **d** c* b**'; // 8 delimiters (* and **)

$converter = new CommonMarkConverter(['max_delimiters_per_line' => 6]);
echo $converter->convert($markdown);

// <p><em>a</em> **b *c <strong>d</strong> c* b**</p>
```

## Additional Filtering

Although this library does offer these security features out-of-the-box, some users may opt to also run the HTML output through additional filtering layers (like HTMLPurifier). If you do this, make sure you **thoroughly** test your additional post-processing steps and configure them to work properly with the types of HTML elements and attributes that converted Markdown might produce, otherwise, you may end up with weird behavior like missing images, broken links, mismatched HTML tags, etc.
4 changes: 2 additions & 2 deletions docs/_data/menu.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ version:
Getting Started:
'Overview': '/2.6/'
'Installation': '/2.6/installation/'
'Upgrading from 2.3': '/2.6/upgrading/'
'Upgrading from 2.5': '/2.6/upgrading/'
'Changelog': '/2.6/changelog/'
'Support': '/2.6/support/'
Usage:
Expand Down Expand Up @@ -50,7 +50,7 @@ version:
Getting Started:
'Overview': '/2.5/'
'Installation': '/2.5/installation/'
'Upgrading from 2.3': '/2.5/upgrading/'
'Upgrading from 2.4': '/2.5/upgrading/'
'Changelog': '/2.5/changelog/'
'Support': '/2.5/support/'
Usage:
Expand Down

0 comments on commit 88365ec

Please sign in to comment.