The Idea
Writing documentation in Markdown is convenient. It would be even better if you could embed Blade syntax (like @include or variables) inside the Markdown files. Laravel’s Blade engine supports custom file extensions, so you can have it process .md files as well.
Implementation
Install a Markdown Package
Install league/commonmark:
1
| composer require league/commonmark
|
Controller
The example below uses league/commonmark v2 (v1 has a different API):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| use Illuminate\View\Factory;
use League\CommonMark\GithubFlavoredMarkdownConverter;
class DocsController extends Controller
{
private $viewFactory;
public function __construct(Factory $viewFactory)
{
$this->viewFactory = $viewFactory;
// Let .md files be processed by the Blade engine
$this->viewFactory->addExtension('md', 'blade');
}
public function index() {
$converter = new GithubFlavoredMarkdownConverter([
'allow_unsafe_links' => false,
]);
// First compile through Blade, then convert to HTML
return $converter->convert($this->viewFactory->make('demo.md'));
}
}
|
The flow is: Blade first processes the variables and directives in demo.md, outputs a plain Markdown string, then CommonMark converts it to HTML.
