CommonMark: Markdown Done Right - ZendCon 2017

CommonMark
Markdown done right
Colin O’Dell
@colinodell

COLIN O’DELL
Creator & Maintainer of league/commonmark
Lead Web Developer at Unleashed Technologies
Author of PHP 7 Migration Guide e-book
@colinodel
l

LEAGUE/COMMONMARK
A well-written, super-configurable
Markdown parser for PHP based on the
CommonMark spec.
@colinodel
l

ORIGINS OF MARKDOWN
Created in March 2004 by John Gruber
Informal plain-text formatting language
Converts readable text to valid (X)HTML
Primary goal - readability
@colinodel
l

HISTORY OF MARKDOWN
Hello ZendCon!
--------------
Markdown is **awesome**!
1. Foo
2. Bar
3. Baz
Wikipedia entry:
<https://en.wikipedia.org/wiki/Markdown> @colinodel
l

WHY IS IT SUCCESSFUL?
1. Syntax is visually-similar to the resulting
markup
2. Non-strict, forgiving parsing
3. Easily adaptable for different uses
@colinodel
l

68+ DIFFERENT FLAVORS
Source: https://github.com/markdown/markdown.github.com/wiki/Implementations
Actuarius
Blackfriday
BlueCloth
BlueFeather
cebe/markdown
CocoaMarkdown
CommonMark
Discount
ffi-sundown
GHMarkdownParser
Goskirt
Hoedown
Hoep
Knockoff
kramdown
Laika
libpandoc
Lowdown
lua-discount
Lunamark
markdown
markdown-clj
markdown-js
markdown-oo-php
markdown.bash
markdown.lua
markdown.pl
markdown4j
MarkdownDeep
MarkdownJ
MarkdownPapers
MarkdownSharp
marked
Maruku
md2html.awk
Misaka
Mistune
MMMarkdown
MoonShine
MultiMarkdown
node-discount
node-markdown
node-multimarkdown
OMD
Pandoc
Parsedown
Parsedown Extra
peg-markdown
peg-multimarkdown & fork
pegdown
PHP Markdown
PHP Markdown Extra
PHP-Sundown
Python-Discount
python-hoedown
Python-Markdown
Python-Markdown2
RDiscount
Redcarpet
RoboSkirt
Showdown
Sundown
Sundown HS
Sundown.net
text-markdown
texts.js
Txtmark
upskirt.go
@colinodel
l

https://xkcd.com/927/
@colinodel
l

WHY IS IT NEEDED?
*I love Markdown*
I love Markdown
@colinodel
l

WHY IS IT NEEDED?
*I *love* Markdown*
@colinodel
l

WHY IS IT NEEDED? Source: http://johnmacfarlane.net/babelmark2/

30%
WHY IS IT NEEDED?
*I *love* Markdown*
I love Markdown
*I *love* Markdown*
I love Markdown
*I *love* Markdown*
I *love Markdown*
15%
33%
Source: http://johnmacfarlane.net/babelmark2/
@colinodel
l

WHY IS IT NEEDED?
1. > Hello
World!
------
Source: http://johnmacfarlane.net/babelmark2/

COMMONMARK IS…
A strongly defined, highly compatible specification of Markdown.
Written by people from Github, StackOverflow, Reddit, and others.
Spec includes:
 Strict rules (precedence, parsing order, handling edge cases)
 Specific definitions (ex: “whitespace”, “punctuation”)
 624 examples
@colinodel
l

CommonMark: Markdown Done Right - ZendCon 2017

FEATURES
 100% compliance with the CommonMark spec
 Easy to implement
 Easy to customize
 Well-tested
 Decent performance
 (Relatively) stable
@colinodel
l

ADDING LEAGUE/COMMONMARK
$ composer require league/commonmark:^0.15
<?php
$converter = new CommonMarkConverter();
echo $converter->convertToHtml('Hello **ZendCon!**');
@colinodel
l

CONVERSION PROCESS
<http://www.zendcon.com>
<a href="http://www.zendcon.com">
http://www.zendcon.com
</a>
@colinodel
l

CONVERSION PROCESS
Markdow
n
Parse
@colinodel
l

<document>
<paragraph>
<link destination="http://www.zendcon.com">
<text>http://www.zendcon.com</text>
</link>
</paragraph>
</document>
CONVERSION PROCESS
Markdow
n
AST RenderParse
@colinodel
l

CONVERSION PROCESS
</a>
Markdow
n
AST HTMLRenderParse
@colinodel
l

CONVERSION PROCESS
Markdow
n
AST HTMLRenderParse
Add your own custom parser, processor, or renderer
@colinodel
l

EXAMPLE 1: CUSTOM PARSER
</a>
<@colinodell>
<a href="https://twitter.com/colinodell">
@colinodell
</a>
@colinodel
l

class TwitterUsernameAutolinkParser extends AbstractInlineParser {
public function getCharacters() {
return ['<'];
}
public function parse(InlineParserContext $inlineContext) {
// TODO
}
}
@colinodel
l

CURSOR
Learning CommonMark with <@colinodell>!
public function getCharacters()
{
return ['<'];
}
@colinodel
l

return ['<'];
}
$cursor = $inlineContext->getCursor();
}
}
@colinodel
l

CURSOR
getCharacter()
getFirstNonSpaceCharacter(
)
getRemainder()
getLine()
getPosition()
advance()
advanceBy($count)
advanceBySpaceOrTab()
advanceWhileMatches($char
)
advanceToFirstNonSpace()
isIndented()
isAtEnd()
match($regex)
peek($count)
@colinodel
l

CURSOR
getCharacter()
getFirstNonSpaceCharacter(
)
getRemainder()
getLine()
getPosition()
advance()
advanceBy($count)
advanceBySpaceOrTab()
advanceWhileMatches($char
)
advanceToFirstNonSpace()
isIndented()
isAtEnd()
match($regex)
peek($count)
/^<@[A-Za-z0-9_]+>/
@colinodel
l

CUSTOMIZING LEAGUE/COMMONMARK
return ['<'];
}
$cursor = $inlineContext->getCursor();
if ($match = $cursor->match('/^<@[A-Za-z0-9_]+>/')) {
// Remove the starting '<@' and ending '>' that were matched
$username = substr($match, 2, -1);
$profileUrl = 'https://twitter.com/' . $username;
$link = new Link($profileUrl, '@'.$username);
$inlineContext->getContainer()->appendChild($link);
return true;
}
return false;
}
}
@colinodel
l

$environment = Environment::createCommonMarkEnvironment();
$environment->addInlineParser(
new TwitterHandleParser()
);
$converter = new CommonMarkConverter($environment);
$html = $converter->convertToHtml(
"Follow <@colinodell> on Twitter!"
);
@colinodel
l

EXAMPLE 2: CUSTOM AST PROCESSOR
<document>
<paragraph>
<link destination="http://www.zendcon.com">
</link>
</paragraph>
</document>
<document>
<paragraph>
<link destination="https://bit.ly/foo">
</link>
</paragraph>
</document>
@colinodel
l

class ShortenLinkProcessor implements DocumentProcessorInterface {
public function processDocument(Document $document) {
$walker = $document->walker();
while ($event = $walker->next()) {
if ($event->isEntering() && $event->getNode() instanceof Link) {
/** @var Link $linkNode */
$linkNode = $event->getNode();
$originalUrl = $linkNode->getUrl();
$shortUrl = $this->bitly->shorten($originalUrl);
$linkNode->setUrl($shortUrl);
}
}
}
}
@colinodel
l

$environment->addDocumentProcessor(
new ShortenLinkProcessor()
);
$html = $converter->convertToHtml(
"Schedule: <http://www.zendcon.com/schedule>"
);
EXAMPLE 2: CUSTOM AST PROCESSOR
@colinodel
l

EXAMPLE 3: CUSTOM RENDERER
<document>
<paragraph>
<text>Hello World!</text>
</paragraph>
<thematic_break />
</document>
Hello World!
<hr />
Hello World!
<img src="hr.png" />
@colinodel
l

class ImageHorizontalRuleRenderer implements BlockRendererInterface {
public function render(...) {
return new HtmlElement('img', ['src' => 'hr.png']);
}
}
@colinodel
l

$environment->addBlockRenderer(
LeagueCommonMarkBlockElementThematicBreak::class,
new ImageHorizontalRuleRenderer()
);
$html = $converter->convertToHtml("Hello World!nn-----");
@colinodel
l

BUNDLING INTO AN EXTENSION
class MyCustomExtension extends Extension {
public function getInlineParsers() {
return [new TwitterUsernameAutolinkParser()];
}
public function getDocumentProcessors() {
return [new ShortenLinkProcessor()];
}
public function getBlockRenderers() {
return [new ImageHorizontalRuleRenderer()];
}
}
@colinodel
l

BUNDLING INTO AN EXTENSION
$environment->addExtension(new MyCustomExtension());
$html = $converter->convertToHtml("...");
@colinodel
l

WELL-TESTED
 94% code coverage
 Functional tests
 All 624 spec examples
 Library of regression tests
 Unit tests
 Cursor
 Environment
 Utility classes
@colinodel
l

PERFORMANCE
0 20 40 60 80
Parsedown
cebe/markdown gfm
PHP Markdown Extra
league/commonmark
Time (ms)
league/commonmark is ~22-24ms slower
PHP 5.6 PHP 7.1
Tips:
• Choose library based on your
needs
• Cache rendered HTML (100%
boost)
• Use PHP 7 (50% boost)
• Optimize custom functionality
@colinodel
l

STABILITY
 Current version: 0.15.6
 Conforms to CommonMark spec 0.28
 1.0.0 will be released once CommonMark spec is 1.0
 No major stability issues
 Backwards Compatibility Promise:
 No BC breaks to CommonMarkConverter class in 0.x
 Other BC breaks are documented (see UPGRADING.md)
@colinodel
l

Installation & Documentation:
http://github.com/thephpleague/commonmark
Learn More About CommonMark:
http://commonmark.org
Slides / Feedback:
https://joind.in/talk/8da74
@colinodell

CommonMark: Markdown Done Right - ZendCon 2017

More Related Content

What's hot (11)

Similar to CommonMark: Markdown Done Right - ZendCon 2017 (20)

More from Colin O'Dell (20)

Recently uploaded (20)

CommonMark: Markdown Done Right - ZendCon 2017

Editor's Notes