olliecodes/laravel-etched-blade

A Laravel package that uses blade templates to parse and convert markdown to HTML

1.0.4 2021-07-01 14:21 UTC

Requires

• php: ^7.3|^8.0
• illuminate/view: ^8.0
• league/commonmark: ^1.6
• webuni/front-matter: ^1.2

Requires (Dev)

• marcocesarato/php-conventional-changelog: ^1.10
• orchestra/testbench: ^6.17
• phpunit/phpunit: ^9.5

MIT

• Ollie Read

README

Install

Install via composer.

$ composer require olliecodes/laravel-etched-blade

Once installed you'll want to publish the config.

$ php artisan vendor:publish --provider="OllieCodes\Etched\EtchedServiceProvider" --tag=config

If you want to modify the default themes you can publish those too.

$ php artisan vendor:publish --provider="OllieCodes\Etched\EtchedServiceProvider" --tag=views

Requirements

This package requires the following;

• PHP >= 7.3 (Including 8).
• illuminate/view >= 8.0 < 9.0 - The view component from Laravel.
• league/commonmark >= 1.6 < 2.0 - The PHP league commonmark library, used for parsing the Markdown.
• webuni/front-matter >= 1.2 < 2.0 - The front matter parser.

Usage

To render markdown in your blade files you can either do it inline;

@etched
# I am a heading

This is some content

 - I am a list
   - So am I but more
   - I'm the same
 - I'm less than those two
@endetched

Or by including a markdown file (.md)

@include('markdown.content.article-1')

The above references the file markdown/content/article-1.md, and the file will be rendered by etched the same way that blade files normally are.

Themes

You can control the theme used for the rendered markdown in several ways.

Provide it as an argument on the directive.

@etched('simple')
...
@endetched

As an argument when including.

@include('markdown-file', ['theme' => 'simple'])

Or in the front-matter of the markdown.

---
theme: simple
---

I am some content

If no theme is provided the value of etched.defaults.theme is used instead. If multiple are provided, the value from the front-matter will take precedence.

Advanced

All markdown rendering is handled by the OllieCodes\Etched\Etched::render() method.

You can use this method on an instance of Etched

app(\OllieCodes\Etched\Etched::class)->render($content, $theme);

Or using the facade.

\OllieCodes\Etched\Facades\Etched::render($content, $theme);

The second parameter $theme is optional and will default to the config value etched.defaults.theme. The theme will be overridden by the front-matter value if one is provided in the markdown content.