Basic Usage
You may parse Markdown in Statamic by using the Markdown
facade.
Statamic\Facades\Markdown::parse('# Hello World!');
<h1>Hello World!</h1>
By default, Statamic follows the CommonMark spec with a few extra features:
- GFM Tables
- HTML Attributes (eg.
# heading {.someclass #someid}
) - Strikethrough (eg.
~~strikethrough~~
)
A few other extensions are available, but disabled by default:
- Autolinking
- HTML escaping
- Automatic line breaks
Customizing Markdown behavior
Under the hood, we’re using the league/commonmark package which supports all sorts of customization using extensions.
Configuration
You may customize the behavior of the markdown parser by providing a CommonMark config array in config/statamic/markdown.php
. All the available options are outlined in the CommonMark docs. You can override the base options as well as any extension’s options.
You only need to provide the specific options you want to override. For example:
'configs' => [ 'default' => [ 'allow_unsafe_links' => false, 'heading_permalink' => [ 'symbol' => '#', ], ]]
Adding extensions
You may add an extension with the addExtension
or addExtensions
methods. For example, in the boot
method of your AppServiceProvider
, return an extension instance, or an array of them.
<?phpnamespace App\Providers; use Illuminate\Support\ServiceProvider;use Statamic\Facades\Markdown;use League\CommonMark\Extension\Footnote\FootnoteExtension;use League\CommonMark\Extension\TableOfContents\TableOfContentsExtension; class AppServiceProvider extends ServiceProvider{ public function boot() { // Add one extension... Markdown::addExtension(function () { return new FootnoteExtension; }); // or multiple. Markdown::addExtensions(function () { return [new FootnoteExtension, new TableOfContentsExtension]; }); }}
You can find a long list of Markdown Extensions on the CommonMark site, or around on GitHub. We love this Hint Extension by Ueberdosis – you’re seeing it in action, powering this “Hot Tip” box.
Statamic 5.0+ uses CommonMark 2.4, while previous versions used either CommonMark 2.2 or CommonMark 1.6. Keep this in mind when reading docs and looking for extension packages.
Helper Methods
In addition to manually defining and configuring extensions, some frequently used behaviors are wrapped up in methods for you to use.
Method | Description |
---|---|
withAutoLinks() |
Convert URLs and email addresses into links. (eg. http://example.com becomes <a href="http://example.com">http://example.com</a> ) |
withSmartPunctuation() |
Convert plain quotes, dashes, ellipsis, etc into their unicode equivalents. Commonly referred to as “smartypants”. (eg. "CommonMark is the PHP League's Markdown parser" becomes “CommonMark is the PHP League’s Markdown parser” ) |
withMarkupEscaping() |
Converts HTML to entities. Useful for securing input from untrusted users. (eg. <div> becomes <div/> ) |
withAutoLineBreaks() |
Converts newlines into <br> tags. Without this, you need to end a line with a \ or two spaces. |
withStatamicDefaults() |
Enable the default set of extensions that Statamic uses (tables, strikethrough, etc). Without this, you will get a plain parser. |
newInstance($config) |
Gives you a new parser instance using an existing one as a starting point. It will inherit all the extensions and config. Accepts an array that will be merged into the config. |
Custom Parsers
Any methods on the Markdown
facade are forwarded onto the default
Parser. This includes the addExtension
methods described above.
You are free to create additional parsers that are configured independently, with their own configuration and extensions.
Markdown::makeParser($config) // Accepts an optional league/commonmark config array. ->withAutoLinks() ->addExtensions(...) ->parse('# Heading');
If you intend to reuse a parser, you may prefer to create it in one place (like a service provider), and then reference it elsewhere.
Markdown::extend('special', function ($parser) { return $parser ->withStatamicDefaults() ->addExtensions(...);});
Markdown::parser('special')->parse('# Heading');
The closure provides you with a fresh Parser
instance which you can customize as needed.
If you need to provide a config to your custom parser, you can either define it in the config file or pass an array as the second option.
Markdown::extend('special', $config, function ($parser) {//});
Using a custom parser in a modifier
The markdown
modifier accepts an optional argument to choose which parser to use.
{{ text | markdown:special }}
{!! Statamic::modify($text)->markdown('special') !!}
Using a custom parser in a fieldtype
The markdown
fieldtype allows you define the parser
. This will be used when it augments the value, so you don’t need the markdown modifier.
- handle: content field: type: markdown parser: special