8fold/commonmark-fluent-markdown

A fluent API for CommonMark by the PHP League

1.2.0 2023-05-15 19:51 UTC

Requires

• php: ^8.1
• 8fold/commonmark-abbreviations: ^1.2 || ^2.1
• 8fold/commonmark-accessible-heading-permalinks: ^1.0
• 8fold/commonmark-partials: ^1.0
• league/commonmark: ^2.0
• symfony/yaml: ^2.3 || ^3.0 || ^4.0 || ^5.0 || ^6.0

Requires (Dev)

• phpstan/phpstan: ^1.2.0
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.6

MIT

• Josh Bruce

README

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.

Installation

composer require 8fold/commonmark-fluent-markdown

Usage

⚠️ Warning: Users of this library are responsible for sanitizing content.

There are two entry classes:

1. Markdown: Does not follow strictly follow conventions established by the League CommonMark.
2. FluentCommonMark: Tries to mirror the conventions of League CommonMark in a fluent way.

The naming convention for methods that are not part of the League CommonMark implementation follow the convention established by PSR-7.

Methods prefixed by the word with will return a new instance to facilitate immutability.

Markdown

The Markdown class makes some presumptions the FluentCommonMark class does not:

1. You will be using the CommonMarkCoreExtension.
2. There will always be the potential for front matter; therefore, the FrontMatterExtension will always be used to separate front matter from the body.

The Markdown class uses the the default configuration provided by CommonMark with modifications recommended by the security page of the CommonMark documentation.

The Markdown class also affords users the ability to use the 8fold CommonMark Abbreviations and 8fold CommonMark Accessible Heading Permalinks extensions whereas FluentCommonMark is strictly vanilla League CommonMark.

Write some markdown:

# Markdown

Woohoo!

Pass the markdown into the Markdown class and ask for the convertedContent:

use Eightfold\Markdown\Markdown;

print Markdown::create()->convert($markdown);

Output:

<h1>Markdown</h1>
<p>Woohoo!</p>

use Eightfold\Markdown\Markdown;

print Markdown::create()->minified()->convert($markdown);

<h1>Markdown</h1><p>Woohoo!</p>

You can have markdown that is nothing but front matter as well.

---
title: The title
---

use Eightfold\Markdown\Markdown;

print Markdown::create()->minified()->getFrontMatter($markdown);

Output:

[
  'title' => 'The title'
]

The Markdown extends the FluentCommonMark class.

FluentMarkdown

The FluentMarkdown class is designed to mimic the behavior and feel of the CommonMark library. There are additional methods in place to facilitate the fully fluent nature of this library.

Container

The Container class is a singleton that may contain one or more converter configurations.

This is useful if you find yourself instantiating multiple markdown converters:

1. With each server request.
2. With the same configuration and options.

By placing those converters in the Container, they only need to be instantiated once and you should see a performance increase by doing so.

Container::instance()->addConverter(
	Markdown::create()->abbreviations()
)->addConverter(
	FluentCommonMark::create()->descriptionLists()
);

// Returns the Markdown instance (first converter in list)
$html = Container::instance()->converter()->convert('');

// Returns HTML converted by FluentCommonMark insance
$html = Container::instance()->converter()->convertToHtml('');

Extensions

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;
use Eightfold\Markdown\FluentCommonMark;

print Markdown::create()
  ->minified()
  ->gitHubFlavoredMarkdown()
  ->abbreviations()
  ->convert($markdown);

print FluentCommonMark::create()
  ->commonMarkCore()
  ->gitHubFlavoredMarkdown()
  ->abbreviations()
  ->convertToHtml($markdown)
  ->getContent();

The result:

<p><del>strikethrough from GitHub Flavored Markdown</del></p><p>An <abbr title="abbreviation">abbr</abbr> from 8fold Abbreviations.</p>

<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([
    'disallowed_tags' => ['div']
  ]);

Not passing in a configuration results in using the default established by the CommonMark library.

Details

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.

Other

• Code of Conduct
• Contributing
• Governance
• Versioning
• Security
• Coding Standards and Style