I'm a huge fan of Markdown. I use it, literally, everywhere I can. The article that you're reading right now was written in Markdown. If I'm ever making notes, I'm using an application that supports Markdown.
Personally, I find it to be the most consistent way of writing. Yes, there are lots of different flavours but they all have the same base.
Here's an example of some Markdown:
# Let's get started with a heading. This is some **bold** text. These are _italics_. Here is a small bit of `code`
Markdown was inspired by text-to-HTML filters. They're tools designed to take some non-HTML text and transform them into good ol' hypertext.
I won't go over the basics of Markdown in this series. The best place to read about that is on the author's website (John Gruber).
This series will be using tools to transform Markdown that follows the CommonMark specification into HTML.
First thing that you need to do to start using Markdown in a PHP application is, you guessed it, install a Composer package.
Since I'm going to be using the CommonMark specification, we need to use a tool that supports that spec.
Luckily the wonderful people over at The PHP League have developed a package for that,
Run the following command to get it installed:
composer require league/commonmark
Parsing your first Markdown
Now that the package is installed, you can start using it straight away.
First, create a new instance of the
use League\CommonMark\CommonMarkConverter; $converter = new CommonMarkConverter;
Next, call the
convertToHtml() method on the object and pass through a string of Markdown.
use League\CommonMark\CommonMarkConverter; $converter = new CommonMarkConverter; $html = $converter->convertToHtml('# Hello World');
$html variable will now hold the HTML equivalent of the Markdown provided, in this case it will be
Sanitising the Markdown
Since Markdown is converted to HTML, it makes sense that HTML can be written within the Markdown.
When you're transforming user input, this can be risky and might open up the opportunity for an XSS attack.
The PHP League have thought about this though and added an option to the converter that will help out.
To begin using these configuration options, you need to provide an array when constructing the
use League\CommonMark\CommonMarkConverter; $converter = new CommonMarkConverter([ 'html_input' => 'escape' ]); $html = $converter->convertToHtml('# Hello World');
If you now change the Markdown being parsed and include some HTML, the result will be escaped.
use League\CommonMark\CommonMarkConverter; $converter = new CommonMarkConverter([ 'html_input' => 'escape' ]); $html = $converter->convertToHtml('<h1>Hello World</h1>');
After being transformed,
$html will now hold the string
<h1>Hello World</h1> which is the escaped version of the HTML being transformed.
If you're interested in some of the other options available, visit the package's documentation on Configuration.
Thanks for reading this article. In the next instalment, I'll be showing you some helpful extensions you can use to make your Markdown writing experience less painful.
Thanks for reading! 👋