If you don’t already know markdown is a text to html conversion tool for web writers. It allows web writers to not get bogged down with the small imprecisions that occur whilst you copy and paste. Bootstraping a Laravel blog (model, controller and routes) First thing we need is a bootstrapped Laravel app. You can check this previous article in which I create a Laravel + Tailwind CSS project. Once we have our bootstrapped project, lets focus in the blog. First we'd need to create a migration to create the articles table.

Preview your notifications easily with just a couple of lines of code

Sometimes you want to develop beautiful notifications in HTML or markdown format. But how do you style them easily without having to send them every time you've changed something? Laravel offers an out of the box solution for this. In your web.php you can easily return a notification to render it and display it in your web browser.

Let's code!

If you'd like to try this with an easy example you can code along with me. First, we start with creating an example notification:

$ php artisan make:notification InvoicePaid

Secondly, we add the following lines to our web.php to be able to display the notification in our browser:

As the title of this article might confuse, it sounds like we render a Notification, in this case, InvoicePaid. But what we're actually rendering here is the MailMessage we return in the toMail method.

Rendering markdown notifications

Laravel supports sending markdown notifications as well and it would be nice to be able to preview these as well in the browser. For this kind of notifications it requires a little bit more code:

In this case, we use the IlluminateMailMarkdown class to render the markdown to HTML. Go to /notification in your browser to see if it works!

(Bonus!) Rendering On-Demand Notifications

All objects which are using the Notifiable trait can be notified through their desired channel. This is a great out of the box feature from Laravel. But there are times that you'd like to send a notification to an email or mobile number which isn't a Notifiable instance (yet). Laravel calls these On-Demand Notifications. To render On-Demand Notifications in your browser we have the following workaround:

In the background, Laravel uses the AnonymousNotifiable class to send notifications on-demand.

From the About section of league/commonmark package:

• Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.

This package helps us parse markdown in PHP. If you are not familiar with markdown, GitHub has super helpful guide about it here.

Mail in Laravel

Laravel provides simple and easy ways to send emails. There are two options in Laravel to send emails:

• Mailables
• Notifications

I created a poll on Twitter to see how Developers usually send emails in their Laravel apps. Based on the results, seems like Mailable is the go-to choice. We'll also use Mailable to explore further.

(Interesting replies on this tweet, give them a read)

How do you usually send emails in a Laravel app? 👀#Laravel#PHP

Markdown Mailables

Let's generate a markdown mailable using Artisan.

We get two files as a result of this command.

• AppMailNewsletterSubscribed class
• resources/views/emails/newsletter/subscribed.blade.php file

Let's take a look at view file:

We can see that there's a combination of Blade Components and Markdown in this file. These components and others are made available by Laravel, read more about components here. When we send out this mailable, league/commonmark package comes into play and parse this markdown to HTML.

What happens when you Mail::to()→send() ?

We are specifying the recipient in to() method and the mailable class in send() method.

Code Dive

Let's dive into send() method. It leads us to IlluminateMailPendingMail class.

Mailable class is being filled with addresses and then its calling send method on the given Mailer instance. As we can see, $mailer is an instance of class which implements the Mailer contract. Where do we find its concrete class implementation?

Finding the Mailer

When request comes in and Laravel registers the ServiceProviders, part of these providers is IllumiateMailMailServiceProvider. Let's take a look at its register method.

It is binding a singleton of MailManager class and then bindMailer by calling mailer() method on mail.manager singleton above.

• We can already see a Markdown class being registered. We will eventually reach to this class.
• Read more about singleton() and bind() binding methods in the documentation

Laravel Markdown Free

Let's dig into mailer() method of MailManager class.

Laravel Markdown Download

Above code can be roughly translated to:

• Get the default mail driver / default mailer (which is smtp) then call get() method on it. get() method checks if given mailer has already been resolved ( local cache ), otherwise resolve the concrete class for the given mailer.

We found the Mailer concrete class. Yay!

It's located at IlluminateMailMailer. It was kind of obvious, but finding it through code-dive was fun. Alright, moving on...

The Mailer

We are interested in send() method on the Mailer class. Let's take a look:

Laravel Markdown Template

In the send() method it checks if $view is an instance of Mailable , in our case this is true. We are indeed working with Mailable and we passed a mailable from PendingMail class.

Then it sets Mailer on Mailable class itself and then calls send method on the Mailable.

The Mailable

If we were to find concrete class that implements Mailable class, this post will become huge.

Therefore, we are just going to assume that IlluminateMailMailable class is what we need as our NewsletterSubscribed class extends it and it also implements IlluminateContractsMailMailable interface.

In context of our topic, buildView() method is of our interest. Below is its implementation and related methods.

buildMarkdownView() method is where it is initialising Markdown class from container and rendering the markdown view of our NewlsetterSubscribed mail.

Laravel Markdown

The Markdown

In the Markdown class, there are two important methods. render and parse.

And we can finally see inside the parse() method that it utilizes classes from league/commonmark package like CommonMarkConverter and TableExtension etc.

But we never called parse() method from anywhere? And we can see nothing inside the render() method related to markdown either?

Well, parse() method is called from within the email views. Our subscribed.blade.php view uses @component('mail::message') which in-turn uses @component('mail::layout') , and if we take a look at layout component at Mailresourcesviewshtmllayout.blade.php , we see an HTML template with table layout and some styling.

There we see the following code in which parse() method is being called.

When the subscribed view is rendered, parse gets called and our markdown content is parsed using league/commonmark package.

Laravel Markdown Tutorial

Interesting facts about Markdown in Laravel

• Laravel started supporting Markdown syntax in emails **in version 5.4**
• The first package used to parse markdown was erusev/parsedown
• In Laravel v6.0, they switched from erusev/parsedown to league/commonmark for safety features.
• Taylor Otwell removed erusev/parsedown from composer.json and added league/commonmark on 30 Dec, 2019.
• Commit on GitHub can be found on this link

Laravel Markdown App

I hope you enjoyed this post. Next, we will see how Laravel uses league/flysystem package. You can follow me on Twitter or join my newsletter to keep yourself updated.