README

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

kaoken / markdown-it-php

Maintainers

Details