markdown-it-php

This gem is a port of the markdown-it Javascript package by Vitaly Puzrin and Alex Kocharin. Currently synced with markdown-it 14.1.0

Javascript Live demo

• Follows the CommonMark spec + adds syntax extensions & sugar (URL autolinking, typographer).
• Configurable syntax! You can add new rules and even replace existing ones.
• Safe by default.

Table of content

• Install
• Syntax extensions
• References / Thanks
• License

Install

composer:

composer require kaoken/markdown-it-php

Simple

$md = new MarkdownIt();
$result = $md->render('# markdown-it rulezz!');

Single line rendering, without paragraph wrap:

$md = new MarkdownIt();
$result = $md->renderInline('__markdown-it__ rulezz!');

Init with presets and options

(*) presets define combinations of active rules and options. Can be "commonmark", "zero" or "default" (if skipped).

// commonmark mode
$md = new MarkdownIt('commonmark');

// default mode
$md = new MarkdownIt();

// enable everything
$md = new MarkdownIt([
  "html"=>        true,
  "linkify"=>     true,
  "typographer"=> true
]);

// full options list (defaults)
$md = new MarkdownIt([
  "html"=>         false,        // Enable HTML tags in source
  "xhtmlOut"=>     false,        // Use '/' to close single tags (<br />).
                                 // This is only for full CommonMark compatibility.
  "breaks"=>       false,        // Convert '\n' in paragraphs into <br>
  "langPrefix"=>   'language-',  // CSS language prefix for fenced blocks. Can be
                                 // useful for external highlighters.
  "linkify"=>      false,        // Autoconvert URL-like text to links

  // Enable some language-neutral replacement + quotes beautification
  // For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.js
  "typographer"=>  false,

  // Double + single quotes replacement pairs, when typographer enabled,
  // and smartquotes on. Could be either a String or an Array.
  //
  // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
  // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
  "quotes"=> '“”‘’',

  // Highlighter function. Should return escaped HTML,
  // or '' if the source string is not changed and should be escaped externaly.
  // If $result starts with <pre... internal wrapper is skipped.
  "highlight"=> function (/*str, lang*/) { return ''; }
]);

Plugins load

$md = new MarkdownIt()
            ->plugin(plugin1)
            ->plugin(plugin2, opts, ...)
            ->plugin(plugin3);

Syntax highlighting

Apply syntax highlighting to fenced code blocks with the highlight option:
The sample here is only the highlight of the PHP language.

// Actual default values
$md = new MarkdownIt([
  "highlight"=> function ($str, $lang) {
    if ( $lang ) {
      try {
        return highlight_string($str);
      } catch (Exception $e) {}
    }

    return ''; // use external default escaping
  }
]);

Or with full wrapper override (if you need assign class to <pre>):

// Actual default values
$md = new MarkdownIt([
  "highlight"=> function ($str, $lang) {
    if ( $lang ) {
      try {
        return '<pre><code class="hljs">' .
               highlight_string($str) .
               '</code></pre>';
      } catch (Exception $e) {}
    }

    return '<pre><code class="hljs">' . $md->utils->escapeHtml($str) . '</code></pre>';
  }
]);

Linkify

linkify: true uses linkify-it. To configure linkify-it, access the linkify instance through $md->linkify:

$md->linkify->set(['fuzzyEmail'=>false]);  // disables .py as top level domain

Syntax extensions

Embedded (enabled by default):

• Tables (GFM)
• Strikethrough (GFM)

The following plugins are in the kaoken\markdown-it-php\MarkdownIt\Plugins directory:

• subscript \MarkdownItSub
• superscript \MarkdownItSup
• footnote \MarkdownItFootnote
• definition list \MarkdownItDeflist
• abbreviation \MarkdownItAbbr
• emoji \MarkdownItEmoji
• custom container \MarkdownItContainer
• insert \MarkdownItIns
• mark \MarkdownItMark

Manage rules

By default all rules are enabled, but can be restricted by options. On plugin load all its rules are enabled automatically.

// Activate/deactivate rules, with currying
$md = (new MarkdownIt())
            ->disable([ 'link', 'image' ])
            ->enable([ 'link' ])
            ->enable('image');

// Enable everything
$md = new MarkdownIt([
  "html"        => true,
  "linkify"     => true,
  "typographer" => true,
]);

You can find all rules in sources: ParserCore, ParserBlock, ParserInline.

References / Thanks

Thanks to the authors of the original implementation in Javascript, markdown-it:

• Alex Kocharin github/rlidwka
• Vitaly Puzrin github/puzrin

and to John MacFarlane for his work on the CommonMark spec and reference implementations.

Related Links:

• https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, also contains latest spec & online demo.
• http://talk.commonmark.org - CommonMark forum, good place to collaborate developers' efforts.

License

MIT