Skip to content

Commit 3b8b60d

Browse files
colinodellcolinodell
committed
Prepare 2.6 docs
1 parent 0026475 commit 3b8b60d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+4440
-0
lines changed

‎docs/2.6/basic-usage.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
layout: default
3+
title: Basic Usage
4+
description: Basic usage of the CommonMark parser
5+
redirect_from: /basic-usage/
6+
---
7+
8+
# Basic Usage
9+
10+
<i class="fa fa-exclamation-triangle"></i>
11+
**Important:** See the [security](/2.6/security/) section for important details on avoiding security misconfigurations.
12+
13+
The `CommonMarkConverter` class provides a simple wrapper for converting Markdown to HTML:
14+
15+
```php
16+
require __DIR__ . '/vendor/autoload.php';
17+
18+
use League\CommonMark\CommonMarkConverter;
19+
20+
$converter = new CommonMarkConverter();
21+
echo $converter->convert('# Hello World!');
22+
23+
// <h1>Hello World!</h1>
24+
```
25+
26+
Or if you want GitHub-Flavored Markdown:
27+
28+
```php
29+
require __DIR__ . '/vendor/autoload.php';
30+
31+
use League\CommonMark\GithubFlavoredMarkdownConverter;
32+
33+
$converter = new GithubFlavoredMarkdownConverter();
34+
echo $converter->convert('# Hello World!');
35+
36+
// <h1>Hello World!</h1>
37+
```
38+
39+
## Using Extensions
40+
41+
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:
42+
43+
```php
44+
require __DIR__ . '/vendor/autoload.php';
45+
46+
use League\CommonMark\Environment\Environment;
47+
use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
48+
use League\CommonMark\Extension\SmartPunct\SmartPunctExtension;
49+
use League\CommonMark\Extension\Strikethrough\StrikethroughExtension;
50+
use League\CommonMark\MarkdownConverter;
51+
52+
$environment = new Environment();
53+
54+
$environment->addExtension(new InlinesOnlyExtension());
55+
$environment->addExtension(new SmartPunctExtension());
56+
$environment->addExtension(new StrikethroughExtension());
57+
58+
$converter = new MarkdownConverter($environment);
59+
echo $converter->convert('**Hello World!**');
60+
61+
// <p><strong>Hello World!</strong></p>
62+
```
63+
64+
## Configuration
65+
66+
If you're using the `CommonMarkConverter` or `GithubFlavoredMarkdownConverter` class you can pass configuration options directly into their constructor:
67+
68+
```php
69+
use League\CommonMark\CommonMarkConverter;
70+
use League\CommonMark\GithubFlavoredMarkdownConverter;
71+
72+
$converter = new CommonMarkConverter($config);
73+
// or
74+
$converter = new GithubFlavoredMarkdownConverter($config);
75+
```
76+
77+
Otherwise, if you’re using `MarkdownConverter` to customize the extensions in your parser, pass the configuration into the `Environment`'s constructor instead:
78+
79+
```php
80+
use League\CommonMark\Environment\Environment;
81+
use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
82+
use League\CommonMark\MarkdownConverter;
83+
84+
// Here's where we set the configuration array:
85+
$environment = new Environment($config);
86+
87+
// TODO: Add any/all the extensions you wish; for example:
88+
$environment->addExtension(new InlinesOnlyExtension());
89+
90+
// Go forth and convert you some Markdown!
91+
$converter = new MarkdownConverter($environment);
92+
```
93+
94+
See the [configuration section](/2.6/configuration/) for more information on the available configuration options.
95+
96+
## Supported Character Encodings
97+
98+
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.
99+
100+
## Return Value
101+
102+
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

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
layout: default
3+
title: Changelog
4+
description: Important changes made in recent releases
5+
redirect_from: /changelog/
6+
---
7+
8+
# Changelog
9+
10+
All notable changes made in `2.x` releases are shown below. See the [full list of releases](/releases) for the complete changelog.
11+
12+
{% assign releases = site.github.releases | where_exp: "r", "r.name >= '2.6'" | where_exp: "r", "r.name < '3.0'" %}
13+
14+
{% for release in releases %}
15+
16+
## [{{ release.name }}]({{ release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }}
17+
18+
{{ release.body | markdownify }}
19+
{% endfor %}
20+
21+
## Older Versions
22+
23+
Please see the [full list of releases](/releases) for the complete changelog.

‎docs/2.6/configuration.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
layout: default
3+
title: Configuration
4+
redirect_from: /configuration/
5+
---
6+
7+
# Configuration
8+
9+
Many aspects of this library's behavior can be tweaked using configuration options.
10+
11+
You can provide an array of configuration options to the `Environment` or converter classes when creating them:
12+
13+
```php
14+
$config = [
15+
'renderer' => [
16+
'block_separator' => "\n",
17+
'inner_separator' => "\n",
18+
'soft_break' => "\n",
19+
],
20+
'commonmark' => [
21+
'enable_em' => true,
22+
'enable_strong' => true,
23+
'use_asterisk' => true,
24+
'use_underscore' => true,
25+
'unordered_list_markers' => ['-', '*', '+'],
26+
],
27+
'html_input' => 'escape',
28+
'allow_unsafe_links' => false,
29+
'max_nesting_level' => PHP_INT_MAX,
30+
'slug_normalizer' => [
31+
'max_length' => 255,
32+
],
33+
];
34+
```
35+
36+
If you're using the basic `CommonMarkConverter` or `GithubFlavoredMarkdown` classes, simply pass the configuration array into the constructor:
37+
38+
```php
39+
use League\CommonMark\CommonMarkConverter;
40+
use League\CommonMark\GithubFlavoredMarkdownConverter;
41+
42+
$converter = new CommonMarkConverter($config);
43+
// or
44+
$converter = new GithubFlavoredMarkdownConverter($config);
45+
```
46+
47+
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:
48+
49+
```php
50+
use League\CommonMark\Environment\Environment;
51+
use League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension;
52+
use League\CommonMark\MarkdownConverter;
53+
54+
// Here's where we set the configuration array:
55+
$environment = new Environment($config);
56+
57+
// TODO: Add any/all the extensions you wish; for example:
58+
$environment->addExtension(new InlinesOnlyExtension());
59+
60+
// Go forth and convert you some Markdown!
61+
$converter = new MarkdownConverter($environment);
62+
```
63+
64+
Here's a list of the core configuration options available:
65+
66+
- `renderer` - Array of options for rendering HTML
67+
- `block_separator` - String to use for separating renderer block elements
68+
- `inner_separator` - String to use for separating inner block contents
69+
- `soft_break` - String to use for rendering soft breaks
70+
- `html_input` - How to handle HTML input. Set this option to one of the following strings:
71+
- `strip` - Strip all HTML (equivalent to `'safe' => true`)
72+
- `allow` - Allow all HTML input as-is (default value; equivalent to `'safe' => false)
73+
- `escape` - Escape all HTML
74+
- `allow_unsafe_links` - Remove risky link and image URLs by setting this to `false` (default: `true`)
75+
- `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.
76+
- `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
77+
- `instance` - An alternative normalizer to use (defaults to the included `SlugNormalizer`)
78+
- `max_length` - Limits the size of generated slugs (defaults to 255 characters)
79+
- `unique` - Controls whether slugs should be unique per `'document'` (default) or per `'environment'`; can be disabled with `false`
80+
81+
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:
82+
83+
- `commonmark` - Array of options for configuring the CommonMark core extension:
84+
- `enable_em` - Disable `<em>` parsing by setting to `false`; enable with `true` (default: `true`)
85+
- `enable_strong` - Disable `<strong>` parsing by setting to `false`; enable with `true` (default: `true`)
86+
- `use_asterisk` - Disable parsing of `*` for emphasis by setting to `false`; enable with `true` (default: `true`)
87+
- `use_underscore` - Disable parsing of `_` for emphasis by setting to `false`; enable with `true` (default: `true`)
88+
- `unordered_list_markers` - Array of characters that can be used to indicate a bulleted list (default: `["-", "*", "+"]`)
89+
90+
## Environment
91+
92+
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.
93+
94+
[Learn more about customizing the Environment](/2.6/customization/environment/)

0 commit comments

Comments
 (0)