Introduction
If you are a technical writer, you may have used (at least once) in your editor the code
tab, or if you prefer to write articles, using Markdown (like me) I'm certain, you used the backticks to write code.
In today's article, I have great news for you. You can take your highlighted syntax in your blog to the next level, without heavy JavaScript running in the background, or even CSS if you want! Using torchlight package, by @aarondfrancis, and absolutely, for free!
We're going to see an example, on how to use it in the Laravel framework, but you can use it outside the framework for sure.
Requisites
- Knowledge of PHP
- Basic understanding on the Laravel framework
- Laravel artisan commands
Torchlight Clients Support
Torchlight does not support only Laravel, it supports, Jigsaw, CommonMark PHP, Statamic, Livewire, Standalone CLI, Remark JS, and ibis.
If you want to check other clients, you may take a look at the Client Section on the docs.
Installation
To install torchlight, you need to require the package from composer
1composer require torchlight/torchlight-laravel
Get Torchlight Token
If you wish to use torchlight, you may create a new account to obtain an API Key, and it's unlimited, and do not worry, it won't cost you a dime :)
After you generate a new API token, you can copy the key, and paste it in the .env
file
1# TORCHLIGHT2TORCHLIGHT_TOKEN="torch_xxx"
Adding the Middleware
To let the package renders correctly, you may want to put the RenderTorchlight
middleware, at the beginning of your middleware list, in app/Kernel.php
1protected $middleware = [2 \Torchlight\Middleware\RenderTorchlight::class, 3 // ...4];
Configuration
Next step, is publishing the configuration, if you want to customize themes, line numbers...
1php artisan torchlight:install
Torchlight Themes
Torchlight came with lots of themes included (VS Code themes), and you want to check them out, and select one, you may head to the Theme Section, in the website docs.
Torchlight Blade Component
When you are using torchlight in Laravel, you can use the custom blade component, that came with the package, and you can use it inside the blade files.
1<x-torchlight-code language="php">2 echo "Hey There!":3</x-torchlight-code>
You can set the language
you are using as a prop, besides the theme
also
1<x-torchlight-code language="python" theme="github-light">2 print('Hey There!')3</x-torchlight-code>
You may also, want to render a specific file using the torchlight component, using an absolute path
1<x-torchlight-code lanauge="js" contents="{{ base_path('vite.config.js') }}"/>
Like any Laravel component, you can use any attribute you like, such as class
, or id
... you name it.
1<x-torchlight-code class="my-5" id="code-1" language="php">2 echo "Example with class & id attributes";3</x-torchlight-code>
Using Torchlight By Default
If you want to use torchlight package as a default, to highlight your code, when parsing .md
files, you may do the following:
Install Markdown Package
First thing, you may want to install the Laravel Markdown package by @GrahamJCampbell
1composer require graham-campbell/markdown
Publish the assets
1php artisan vendor:publish
Then chose the right vendor assets.
Add Torchlight Extension
After publishing the assets, go to config/markdown.php
file, under the extensions
key, you may add the TorchlightExtension
1use Torchlight\Commonmark\V2\TorchlightExtension; 2return [ 3 /// 4 5 'extensions' => [ 6 League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension::class, 7 League\CommonMark\Extension\Table\TableExtension::class, 8 TorchlightExtension::class, 9 ],10];
After that, you are good to go, and all what you need to do, is using the markdown
directive on your blade file, or use the Markdown
facade, you want a backend solution.
You may take a look at the package documentation, to learn more.
Conclusion
Alright, this is all what you need to know, to be up & running using torchlight package, but the fun still out there, if you want to get more! If you are interested, you may take a look, and know about all the features that the package provide, such as ANNOTATIONS, line numbers, diff indicators... and many more!
If you like this articles, follow me on Twitter to learn more about that kind of stuff, and level up your web skills.
Peace 👌