Prepare 2.6 docs

docs/2.6/basic-usage.md

@@ -0,0 +1,102 @@
+---
+layout: default
+title: Basic Usage
+description: Basic usage of the CommonMark parser
+redirect_from: /basic-usage/
+---
+
+# Basic Usage
+
+<i class="fa fa-exclamation-triangle"></i>
+**Important:** See the [security](/2.6/security/) section for important details on avoiding security misconfigurations.
+
+The `CommonMarkConverter` class provides a simple wrapper for converting Markdown to HTML:
+
+```php
+require __DIR__ . '/vendor/autoload.php';
+
+use League\CommonMark\CommonMarkConverter;
+
+$converter = new CommonMarkConverter();
+echo $converter->convert('# Hello World!');
+
+// <h1>Hello World!</h1>
+```
+
+Or if you want GitHub-Flavored Markdown:
+
+```php
+require __DIR__ . '/vendor/autoload.php';
+
+use League\CommonMark\GithubFlavoredMarkdownConverter;
+
+$converter = new GithubFlavoredMarkdownConverter();
+echo $converter->convert('# Hello World!');
+
+// <h1>Hello World!</h1>
+```
+
+## Using Extensions
+
+The `CommonMarkConverter` and `GithubFlavoredMarkdownConverter` shown above automatically configure [the environment](/2.6/customization/environment/) for you, but if you want to use [additional extensions](/2.6/customization/extensions/) you'll need to avoid those classes and use the generic `MarkdownConverter` class instead to customize [the environment](/2.6/customization/environment/) with whatever extensions you wish to use:
+
+```php
+require __DIR__ . '/vendor/autoload.php';
+
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
+use League\CommonMark\Extension\SmartPunct\SmartPunctExtension;
+use League\CommonMark\Extension\Strikethrough\StrikethroughExtension;
+use League\CommonMark\MarkdownConverter;
+
+$environment = new Environment();
+
+$environment->addExtension(new InlinesOnlyExtension());
+$environment->addExtension(new SmartPunctExtension());
+$environment->addExtension(new StrikethroughExtension());
+
+$converter = new MarkdownConverter($environment);
+echo $converter->convert('**Hello World!**');
+
+// <p><strong>Hello World!</strong></p>
+```
+
+## Configuration
+
+If you're using the `CommonMarkConverter` or `GithubFlavoredMarkdownConverter` class you can pass configuration options directly into their constructor:
+
+```php
+use League\CommonMark\CommonMarkConverter;
+use League\CommonMark\GithubFlavoredMarkdownConverter;
+
+$converter = new CommonMarkConverter($config);
+// or
+$converter = new GithubFlavoredMarkdownConverter($config);
+```
+
+Otherwise, if you’re using `MarkdownConverter` to customize the extensions in your parser, pass the configuration into the `Environment`'s constructor instead:
+
+```php
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
+use League\CommonMark\MarkdownConverter;
+
+// Here's where we set the configuration array:
+$environment = new Environment($config);
+
+// TODO: Add any/all the extensions you wish; for example:
+$environment->addExtension(new InlinesOnlyExtension());
+
+// Go forth and convert you some Markdown!
+$converter = new MarkdownConverter($environment);
+```
+
+See the [configuration section](/2.6/configuration/) for more information on the available configuration options.
+
+## 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 `convert()` 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/2.6/changelog.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Changelog
+description: Important changes made in recent releases
+redirect_from: /changelog/
+---
+
+# 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.6'" | 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/2.6/configuration.md

@@ -0,0 +1,94 @@
+---
+layout: default
+title: Configuration
+redirect_from: /configuration/
+---
+
+# Configuration
+
+Many aspects of this library's behavior can be tweaked using configuration options.
+
+You can provide an array of configuration options to the `Environment` or converter classes when creating them:
+
+```php
+$config = [
+    'renderer' => [
+        'block_separator' => "\n",
+        'inner_separator' => "\n",
+        'soft_break'      => "\n",
+    ],
+    'commonmark' => [
+        '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' => PHP_INT_MAX,
+    'slug_normalizer' => [
+        'max_length' => 255,
+    ],
+];
+```
+
+If you're using the basic `CommonMarkConverter` or `GithubFlavoredMarkdown` classes, simply pass the configuration array into the constructor:
+
+```php
+use League\CommonMark\CommonMarkConverter;
+use League\CommonMark\GithubFlavoredMarkdownConverter;
+
+$converter = new CommonMarkConverter($config);
+// or
+$converter = new GithubFlavoredMarkdownConverter($config);
+```
+
+Otherwise, if you're using `MarkdownConverter` to customize the extensions in your parser, pass the configuration into the [Environment](/2.6/customization/environment/)'s constructor instead:
+
+```php
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
+use League\CommonMark\MarkdownConverter;
+
+// Here's where we set the configuration array:
+$environment = new Environment($config);
+
+// TODO: Add any/all the extensions you wish; for example:
+$environment->addExtension(new InlinesOnlyExtension());
+
+// Go forth and convert you some Markdown!
+$converter = new MarkdownConverter($environment);
+```
+
+Here's a list of the core configuration options available:
+
+- `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
+- `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: `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
+  - `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`
+
+Additional configuration options are available for most of the [available extensions](/2.6/customization/extensions/) - refer to their individual documentation for more details.  For example, the CommonMark core extension offers these additional options:
+
+- `commonmark` - Array of options for configuring the CommonMark core extension:
+  - `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 indicate a bulleted list (default: `["-", "*", "+"]`)
+
+## 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.
+
+[Learn more about customizing the Environment](/2.6/customization/environment/)