1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
---
layout: default
title: Front Matter Extension
description: The Front Matter extension automatically parses YAML front matter from your Markdown.
---
# Front Matter Extension
The `FrontMatterExtension` adds the ability to parse YAML front matter from the Markdown document and include that in the return result.
## Installation
This extension is bundled with `league/commonmark`. This library can be installed via Composer:
```bash
composer require league/commonmark
```
See the [installation](/2.2/installation/) section for more details.
You will also need to install `symfony/yaml` or the [YAML extension for PHP](https://www.php.net/manual/book.yaml.php) to use this extension. For `symfony/yaml`:
```bash
composer require symfony/yaml
```
(You can use any version of `symfony/yaml` 2.3 or higher, though we recommend using 4.0 or higher.)
## Front Matter Syntax
This extension follows the [Jekyll Front Matter syntax](https://jekyllrb.com/docs/front-matter/). The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
```markdown
---
layout: post
title: I Love Markdown
tags:
- test
- example
---
# Hello World!
```
This will produce a front matter array similar to this:
```php
$parsedFrontMatter = [
'layout' => 'post',
'title' => 'I Love Markdown',
'tags' => [
'test',
'example',
],
];
```
And the HTML output will only contain the one heading:
```html
<h1>Hello World!</h1>
```
## Usage
Configure your `Environment` as usual and add the `FrontMatterExtension`:
```php
use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
use League\CommonMark\Extension\FrontMatter\Output\RenderedContentWithFrontMatter;
use League\CommonMark\MarkdownConverter;
// Define your configuration, if needed
$config = [];
// Configure the Environment with all the CommonMark parsers/renderers
$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());
// Add the extension
$environment->addExtension(new FrontMatterExtension());
// Instantiate the converter engine and start converting some Markdown!
$converter = new MarkdownConverter($environment);
// A sample Markdown file with some front matter:
$markdown = <<<MD
---
layout: post
title: I Love Markdown
tags:
- test
- example
---
# Hello World!
MD;
$result = $converter->convert($markdown);
// Grab the front matter:
if ($result instanceof RenderedContentWithFrontMatter) {
$frontMatter = $result->getFrontMatter();
}
// Output the HTML using any of these:
echo $result; // implicit string cast
// or:
echo (string) $result; // explicit string cast
// or:
echo $result->getContent();
```
### Parsing Front Matter Only
You don't have to parse the entire file (including all the Markdown) if you only want the front matter. You can either instantiate the front matter parser yourself and call it directly, like this:
```php
use League\CommonMark\Extension\FrontMatter\Data\LibYamlFrontMatterParser;
use League\CommonMark\Extension\FrontMatter\Data\SymfonyYamlFrontMatterParser;
use League\CommonMark\Extension\FrontMatter\FrontMatterParser;
$markdown = '...'; // TODO: Load some Markdown content somehow
// For `symfony/yaml`
$frontMatterParser = new FrontMatterParser(new SymfonyYamlFrontMatterParser());
// For YAML extension
$frontMatterParser = new FrontMatterParser(new LibYamlFrontMatterParser());
$result = $frontMatterParser->parse($markdown);
var_dump($result->getFrontMatter()); // The parsed front matter
var_dump($result->getContent()); // Markdown content without the front matter
```
Or you can use the `getFrontMatterParser()` method from the extension:
```php
use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
$markdown = '...'; // TODO: Load some Markdown content somehow
$frontMatterExtension = new FrontMatterExtension();
$result = $frontMatterExtension->getFrontMatterParser()->parse($markdown);
var_dump($result->getFrontMatter()); // The parsed front matter
var_dump($result->getContent()); // Markdown content without the front matter
```
This latter approach may be more convenient if you have already instantiated a `FrontMatterExtension` object you're adding to the `Environment` somewhere and just want to call that.
|
