Copy of thephpleague/commonark docs

Signed-off-by: Mark Carver <[email protected]>

docs/.gitignore

@@ -0,0 +1 @@
+.jekyll-cache

docs/1.0/basic-usage.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: Basic Usage
+description: Basic usage of the CommonMark parser
+---
+
+Basic Usage
+==============
+
+The `CommonMarkConverter` class provides a simple wrapper for converting Markdown to HTML:
+
+~~~php
+<?php
+
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter();
+echo $converter->convertToHtml('# Hello World!');
+
+// <h1>Hello World!</h1>
+~~~
+
+Or if you want Github-Flavored Markdown:
+
+```php
+<?php
+
+use League\CommonMark\GithubFlavoredMarkdownConverter;
+
+$converter = new GithubFlavoredMarkdownConverter();
+echo $converter->convertToHtml('# Hello World!');
+
+// <h1>Hello World!</h1>
+```
+
+<i class="fa fa-exclamation-triangle"></i>
+**Important:** See the [security](/2.0/security/) section for important details on avoiding security misconfigurations.
+
+[Additional customization](/2.0/customization/overview/) is also possible, and we have many handy [extensions](/2.0/extensions/) to enable additional syntax and features.
+
+## Supported Character Encodings
+
+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.
+
+## Return Value
+
+The `convertToHtml()` method actually returns an instance of `League\CommonMark\Output\RenderedContentInterface`.  You can cast this (implicitly, as shown above, or explicitly) to a `string` or call `getContent()` to get the final HTML output.

docs/1.0/changelog.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Changelog
+description: Important changes made in recent releases
+---
+
+# Changelog
+
+All notable changes made in `2.x` releases are shown below. See the [full list of releases](/releases) for the complete changelog.
+
+{% assign releases = site.github.releases | where_exp: "r", "r.name >= '2.0'" | where_exp: "r", "r.name < '3.0'" %}
+
+{% for release in releases %}
+## [{{ release.name }}]({{ release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }}
+{{ release.body | markdownify }}
+{% endfor %}
+
+## Older Versions
+
+Please see the [full list of releases](/releases) for the complete changelog.

docs/1.0/configuration.md

@@ -0,0 +1,63 @@
+---
+layout: default
+title: Configuration
+---
+
+Configuration
+=============
+
+You can provide an array of configuration options to the `CommonMarkConverter` when creating it:
+
+~~~php
+<?php
+
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter([
+    'renderer' => [
+        'block_separator' => "\n",
+        'inner_separator' => "\n",
+        'soft_break'      => "\n",
+    ],
+    'enable_em' => true,
+    'enable_strong' => true,
+    'use_asterisk' => true,
+    'use_underscore' => true,
+    'unordered_list_markers' => ['-', '*', '+'],
+    'html_input' => 'escape',
+    'allow_unsafe_links' => false,
+    'max_nesting_level' => INF,
+]);
+~~~
+
+Here's a list of currently-supported options:
+
+* `renderer` - Array of options for rendering HTML
+  * `block_separator` - String to use for separating renderer block elements
+  * `inner_separator` - String to use for separating inner block contents
+  * `soft_break` - String to use for rendering soft breaks
+* `enable_em` - Disable `<em>` parsing by setting to `false`; enable with `true` (default: `true`)
+* `enable_strong` - Disable `<strong>` parsing by setting to `false`; enable with `true` (default: `true`)
+* `use_asterisk` - Disable parsing of `*` for emphasis by setting to `false`; enable with `true` (default: `true`)
+* `use_underscore` - Disable parsing of `_` for emphasis by setting to `false`; enable with `true` (default: `true`)
+* `unordered_list_markers` - Array of characters that can be used to indicated a bulleted list (default: `["-", "*", "+"]`)
+* `html_input` - How to handle HTML input.  Set this option to one of the following strings:
+  - `strip` - Strip all HTML (equivalent to `'safe' => true`)
+  - `allow` - Allow all HTML input as-is (default value; equivalent to `'safe' => false)
+  - `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: infinite). Setting this to a positive integer can help protect against long parse times and/or segfaults if blocks are too deeply-nested. Added in 0.17.
+
+Additional configuration options are available for some of the [available extensions](/2.0/customization/extensions/) - refer to their individual documentation for more details.
+
+## Environment
+
+The configuration is ultimately passed to (and managed via) the `Environment`.  If you're creating your own `Environment`, simply pass your config array into its constructor instead.
+
+The `Environment` also exposes three methods for managing the configuration:
+
+* `setConfig(array $config = [])` - Replace the current configuration with something else
+* `mergeConfig(array $config = [])` - Recursively merge the current configuration with the given options
+* `getConfig(string $key, $default = null)` - Returns the config value. For nested configs, use a `/`-separate path; for example: `renderer/soft_break`
+
+[Learn more about customizing the Environment](/2.0/customization/environment/)

docs/1.0/index.md

@@ -0,0 +1,46 @@
+---
+layout: default
+title: Overview
+---
+
+<img class="banner" src="/images/commonmark-banner.png" alt="CommonMark for PHP" />
+
+# Overview
+
+[![Author](https://img.shields.io/badge/[email protected]?style=flat-square)](https://twitter.com/colinodell)
+[![Latest Version](https://img.shields.io/packagist/v/league/commonmark.svg?style=flat-square)](https://packagist.org/packages/league/commonmark)
+[![Total Downloads](https://img.shields.io/packagist/dt/league/commonmark.svg?style=flat-square)](https://packagist.org/packages/league/commonmark)
+[![Software License](https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square)](LICENSE)
+[![Build Status](https://img.shields.io/github/workflow/status/thephpleague/commonmark/Tests/latest.svg?style=flat-square)](https://github.com/thephpleague/commonmark/actions?query=workflow%3ATests+branch%3Alatest)
+[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/thephpleague/commonmark.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure)
+[![Quality Score](https://img.shields.io/scrutinizer/g/thephpleague/commonmark.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/commonmark)
+
+{{ site.data.project.highlights.description }}
+
+## Installation
+
+This library can be installed via Composer:
+
+~~~bash
+composer require league/commonmark
+~~~
+
+See the [installation](/2.0/installation/) section for more details.
+
+## Basic Usage
+
+Simply instantiate the converter and start converting some Markdown to HTML!
+
+~~~php
+<?php
+
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter();
+echo $converter->convertToHtml('# Hello World!');
+
+// <h1>Hello World!</h1>
+~~~
+
+<i class="fa fa-exclamation-triangle"></i>
+**Important:** See the [basic usage](/2.0/basic-usage/) and [security](/2.0/security/) sections for important details.

docs/1.0/installation.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Installation
+description: Instructions on how to install the league/commonmark library
+---
+
+# Installation
+
+The recommended installation method is via Composer.
+
+In your project root just run:
+
+~~~bash
+composer require league/commonmark:^2.0
+~~~
+
+Ensure that you’ve set up your project to [autoload Composer-installed packages](https://getcomposer.org/doc/00-intro.md#autoloading).
+
+## 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 compatibility**; for example: `^2.0`.  This is equivalent to `>=2.0 <3.0`.

docs/1.0/security.md

@@ -0,0 +1,92 @@
+---
+layout: default
+title: Security
+description: How to configure league/commonmark against possible security issues when handling untrusted user input
+---
+
+Security
+========
+
+In order to be fully compliant with the CommonMark spec, certain security settings are disabled by default.  You will want to configure these settings if untrusted users will be providing the Markdown content:
+
+ - `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
+
+Further information about each option can be found below.
+
+## HTML Input
+
+**All HTML input is unescaped by default.**  This behavior ensures that league/commonmark is 100% compliant with the CommonMark spec.
+
+If you're developing an application which renders user-provided Markdown from potentially untrusted users, you are **strongly** encouraged to set the `html_input` option in your configuration to either `escape` or `strip`:
+
+### Example - Escape all raw HTML input:
+
+~~~php
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter(['html_input' => 'escape']);
+echo $converter->convertToHtml('<script>alert("Hello XSS!");</script>');
+
+// &lt;script&gt;alert("Hello XSS!");&lt;/script&gt;
+~~~
+
+### Example - Strip all HTML from the input:
+~~~php
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter(['html_input' => 'strip']);
+echo $converter->convertToHtml('<script>alert("Hello XSS!");</script>');
+
+// (empty output)
+~~~
+
+**Failing to set this option could make your site vulnerable to cross-site scripting (XSS) attacks!**
+
+See the [configuration](/2.0/configuration/) section for more information.
+
+## Unsafe Links
+
+Unsafe links are also allowed by default due to CommonMark spec compliance.  An unsafe link is one that uses any of these protocols:
+
+ - `javascript:`
+ - `vbscript:`
+ - `file:`
+ - `data:` (except for `data:image` in png, gif, jpeg, or webp format)
+
+To prevent these from being parsed and rendered, you should set the `allow_unsafe_links` option to `false`.
+
+## Nesting Level
+
+**No maximum nesting level is enforced by default.**  Markdown content which is too deeply-nested (like 10,000 nested blockquotes: '> > > > > ...') [could result in long render times or segfaults](https://github.com/thephpleague/commonmark/issues/243#issuecomment-217580285).
+
+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;
+
+$markdown = str_repeat('> ', 10000) . ' Foo';
+
+$converter = new CommonMarkConverter(['max_nesting_level' => 5]);
+echo $converter->convertToHtml($markdown);
+
+// <blockquote>
+//   <blockquote>
+//     <blockquote>
+//       <blockquote>
+//         <blockquote>
+//           <p>&gt; &gt; &gt; &gt; &gt; &gt; &gt; ... Foo</p></blockquote>
+//       </blockquote>
+//     </blockquote>
+//   </blockquote>
+// </blockquote>
+~~~
+
+See the [configuration](/2.0/configuration/) section for more information.
+
+## 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.