Download the PHP package 8fold/commonmark-fluent-markdown without Composer

8fold Fluent Markdown for CommonMark

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

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:

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

Output:

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

Output:

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.

Extensions

Each internal CommonMark extension is available via the fluent API along with 8fold Abbreviations:

Setting the extensions and printing the result:

The result:

If the extension accepts a configuration, you can pass it into the method and the primary configuration will be modified accordingly.

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