Customizing Markdown

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.

<?php
namespace 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];
        }); 
    }
}

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.

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.

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