A fluent API for use with the highly-extensible CommonMark parser from the league of extraordinary packages.
We try to put off instantiation and execution until the last possible moment.
composer require 8fold/commonmark-fluent-markdownWrite some markdown:
# Markdown
Woohoo!Pass the markdown into the Markdown class and ask for the convertedContent:
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown)->convertedContent();Output:
<h1>Markdown</h1>
<p>Woohoo!</p>You can also go straight to the output:
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown);Same output as before.
If you are using YAML front matter, you can access it at any time via the frontMatter method:
---
title: Front matter
---
Some content.Getting the front matter:
use Eightfold\Markdown\Markdown;
$frontMatter = Markdown::create($markdown)
->frontMatter();
var_dump($frontMatter);
// output:
// array(
// 'title' => 'Front matter'
// )The native CommonMark extension is used to accomplish this. However, for the purposes of Fluent Markdown, we do not characterize it the same way. This returns metadata, not rendered HTML.
Each internal CommonMark extension is available via the fluent API along with 8fold Abbreviations:
---
title: Front matter
---
~~strikethrough from GitHub Flavored Markdown~~
An [.abbr](abbreviation) from 8fold Abbreviations.Setting the extensions and printing the result:
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown)
->gitHubFlavoredMarkdown()
->abbreviations();The result:
<p><del>strikethrough from GitHub Flavored Markdown</del></p>
<p>An <abbr title="abbreviation">abbr</abbr> from 8fold Abbreviations.</p>If the extension accepts a configuration, you can pass it into the method and the primary configuration will be modified accordingly.
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown)
->disallowedRawHtml(['div']);Not passing in a configuration results in using the default established by the CommonMark library.
The non-extension-related fluent API methods can be found in the
FluentApi trait.
The primary capabilities afforded by the fluent API are:
- adding or modifying a CommonMark-compliant configuration and
- adding or resetting extensions (if not using the fluent API extension methods).
Note: Adding extensions works differently than you would with CommonMark. First, you can add more than one extension at a time. Second, Fluent Markdown takes the full class name, not an instance of the class; in keeping with our desire to be just-in-time and lazy.
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown)
->addExtensions(
\League\CommonMark\Extension\Mention\MentionExtension::class,
'\Eightfold\CommonMarkAbbreviations\AbbreviationExtension'
);The output of CommonMark tends to render each block on a new line.
Block 1
Block 2Output:
<p>Block 1</p>
<p>Block 2</p>In keeping with 8fold XML Builder and HTML Builder, which render XML and HTML as a flat string, Fluent Markdown provides the minified method to accomplish the same:
use Eightfold\Markdown\Markdown;
print Markdown::create($markdown)->minified();Output:
<p>Block 1</p><p>Block 2</p>For longer documents the removal of tabs and carriage returns can add up to quite a bit in the response.
This is actually our third foray into wrapping CommonMark.
CommonMark has been a staple in 8fold web development since inception. As we've progressed and continued to slowly evolve our own XML and HTML generating packages and used those solutions in an array of websites, CommonMark has been featured front and center, as it were.
Given how much CommonMark is used in our various projects and our desire to be loosely coupled with any solutions we don't write ourselves, I think we've come to a solution that accomplishes both those missions.
Minimal code to start, configure, and render HTML. A consistent API to reduce impact as CommonMark continues to evolve.
