Markdown for Laravel

This is a complete guide on how to implement markdown into your Laravel project for a variety of scenarios. We will first start out with installing markdown, and getting it configured.

Than we will go trough a few scenarios that you might want to use markdown for.

Laravel Markdown

We are going to be using the Laravel Markdown package by Graham Cambell

First, we will install the package with composer.

1composer require graham-campbell/markdown:14.0.x-dev

Once installed, if you are not using automatic package discovery, then you need to register the GrahamCampbell\Markdown\MarkdownServiceProvider service provider in your config/app.php.

Now will need to publish the vendor files

1php artisan vendor:publish

You may be asked to select which files to publish, be sure to publish GrahamCampbell\Markdown\MarkdownServiceProvider

Torchlight

Next, we need to install code highlighting with torchlight. Be sure to provide attribution if you do not have the premium version of torchlight to help support the project team that has developed this package.

Installing Blade Component

This will let you use the torchlight blade component in any file directly without having to do markdown syntax.

1// example of how you can use torchlight as a blade component
2<pre><x-torchlight-code language='php'>
3    echo "Hello World!";
4</x-torchlight-code></pre>

First you need to create a new torchlight account

1https://app.torchlight.dev/register?plan=free_month

Once you are logged in, you will need to navigate to Tokens and generate a new API Token. You can call it whatever you want.

Be sure to copy the token that is generated, as you will not see it again! Note that this is an example token, and it won't actually work.

1torch_sXs1dbmkh3ne7XzAKGoqdXeAkNmLqmUsFXPV8esY

Now that you have your token, go to your .ENV file and create a new record.

1TORCHLIGHT_TOKEN = torch_sXs1dbmkh3ne7XzAKGoqdXeAkNmLqmUsFXPV8esY

Next go to Http/Kernel.php and include it in the middleware

1protected $middleware = [
2    \Torchlight\Middleware\RenderTorchlight::class,
3    ...
4];

Now we publish the configuration file with the following command.

1php artisan torchlight:install

You are done! Check out the full docs for more configuration options https://torchlight.dev/docs/clients/laravel but you can now use the blade component in your laravel project wherever it may be needed.

Markdown Highlighting

If you want to use the torchlight style code highlighting in the Laravel Markdown package, than you will need to setup the commonmark extension for it.

First we install it with composer

1composer require torchlight/torchlight-commonmark

Next we need to enable the extension in the package. Open markdown.php and add Torchlight\Commonmark\V2\TorchlightExtension::class,

1'extensions' => [
2    Torchlight\Commonmark\V2\TorchlightExtension::class,
3    ...
4],

You need to publish the config file with

1php artisan torchlight:install

Tailwind CSS Config

If you are using Tailwind, you have an extra step to make sure everything looks good. You

Open resources\css\app.css and the following styling

 1@import 'tailwindcss/base';
 2@import 'tailwindcss/components';
 3@import 'tailwindcss/utilities';
 4 
 5@layer components {
 6    /*
 7    Margin and rounding are personal preferences,
 8    overflow-x-auto is recommended.
 9    */
10    pre {
11        @apply my-4 rounded overflow-x-auto;
12    }
13 
14    /*
15    Add some vertical padding and expand the width
16    to fill its container. The horizontal padding
17    comes at the line level so that background
18    colors extend edge to edge.
19    */
20    pre code.torchlight {
21        @apply block py-4 min-w-max;
22    }
23 
24    /*
25    Horizontal line padding.
26    */
27    pre code.torchlight .line {
28        @apply px-4;
29    }
30 
31    /*
32    Push the code away from the line numbers and
33    summary caret indicators.
34    */
35    pre code.torchlight .line-number,
36    pre code.torchlight .summary-caret {
37        @apply mr-4;
38    }
39}

Run npm run watch or npm run dev and everything should work.

Commonmark Extensions

You can extend the functionality of markdown with your own package or using some of the CommonMark packages from the documentation.

For packages that are on that list you just need to go to markdown.php and add a new item in the extensions section.

We will add Autolinks as an example. https://commonmark.thephpleague.com/2.2/extensions/autolinks/

In the documentation you will see usage and take a look at how it is setup.

1use League\CommonMark\Environment\Environment;
2use League\CommonMark\Extension\Autolink\AutolinkExtension;
3use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
4use League\CommonMark\MarkdownConverter;
5...

We are focusing only on extension line

1use League\CommonMark\Extension\Autolink\AutolinkExtension;

Now we can go to markdown.php file and find the extensions section. We duplicate the line for Table\TableExtension and replace it with Autolink\AutolinkExtension. The code will look like the example below.

1'extensions' => [
2        League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension::class,
3        League\CommonMark\Extension\Table\TableExtension::class,
4        Torchlight\Commonmark\V2\TorchlightExtension::class,
5        League\CommonMark\Extension\Autolink\AutolinkExtension::class,
6    ],

Adding Attributes

Enabling attributes will allow you to add custom classes to elements and add ids, which you can link too with anchor tags. It comes very handy if you want to make documentation style markdown pages.

Just need to add this to the markdown.php file

1League\CommonMark\Extension\Attributes\AttributesExtension::class,

These are the two new syntax you will be a ble to use.

1// adding custom classes
2## Header {.header-name}
3 <h2 class="header-name">Header</h2>
4 
5// adding attributes
6## Header{#header-name}
7<h2 id="header-name">Header</h2>