Getting Started

Understanding Prezet's Configuration File

The configuration file is published as part of the package's installation command, but it can be manually published by running the following command:

1php artisan vendor:publish --provider="BenBjurstrom\Prezet\PrezetServiceProvider" --tag=prezet-config

After installation the configuration file will look like this:

 1<?php
 2 
 3return [
 4    'filesystem' => [
 5        'disk' => env('PREZET_FILESYSTEM_DISK', 'prezet'),
 6    ],
 7 
 8    'data' => [
 9        'frontmatter' => BenBjurstrom\Prezet\Data\FrontmatterData::class,
10    ],
11 
12    'commonmark' => [
13        'extensions' => [
14            League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension::class,
15            League\CommonMark\Extension\FrontMatter\FrontMatterExtension::class,
16            League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkExtension::class,
17            BenBjurstrom\Prezet\Extensions\MarkdownBladeExtension::class,
18            BenBjurstrom\Prezet\Extensions\MarkdownImageExtension::class,
19        ],
20 
21        'config' => [
22            'heading_permalink' => [
23                'html_class' => 'mr-2 scroll-mt-12',
24                'id_prefix' => 'content',
25                'apply_id_to_heading' => false,
26                'heading_class' => '',
27                'fragment_prefix' => 'content',
28                'insert' => 'before',
29                'min_heading_level' => 2,
30                'max_heading_level' => 3,
31                'title' => 'Permalink',
32                'symbol' => '#',
33                'aria_hidden' => true,
34            ],
35        ],
36    ],
37 
38    'image' => [
39        'widths' => [
40            480, 640, 768, 960, 1536,
41        ],
42 
43        'sizes' => '92vw, (max-width: 1024px) 92vw, 768px',
44    ],
45];

#Filesystem Configuration

The filesystem.disk key allows you to specify the disk where your markdown files are stored. By default, Prezet uses the prezet disk. You can change this by updating the PREZET_FILESYSTEM_DISK environment variable in your .env file.

#Data Classes

These classes are used to store markdown information in a validated DTO. You can override the default classes here. For example:

1'data' => [
2    'frontmatter' => BenBjurstrom\Prezet\Data\FrontmatterData::class,
3],

The frontmatter key links to the package's FrontmatterData class. If you want to override it, you would create your own front matter class, add the additional properties that you want, and then update the config file to use that class for the front matter.

To learn more about customizing front matter, see the Customizing Front Matter article. If you want to learn more about how Prezet uses front matter, check out the Front Matter Features article.

#CommonMark Configuration

Here we can configure the CommonMark parser and specify its extensions:

 1'commonmark' => [
 2    'extensions' => [
 3        League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension::class,
 4        League\CommonMark\Extension\FrontMatter\FrontMatterExtension::class,
 5        League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkExtension::class,
 6        BenBjurstrom\Prezet\Extensions\MarkdownBladeExtension::class,
 7        BenBjurstrom\Prezet\Extensions\MarkdownImageExtension::class,
 8    ],
 9    // ... config options
10],

The included extensions are:

  1. CommonMarkCoreExtension: Provides core CommonMark functionality.

  2. FrontMatterExtension: Pulls the front matter from a markdown post for processing and SEO tag generation.

  3. HeadingPermalinkExtension: Creates linkable headings in the body of the markdown content.

  4. MarkdownBladeExtension: A custom extension that allows you to include Blade components in your markdown files. To learn more about this feature see the documentation on using Blade Components in Markdown.

  5. MarkdownImageExtension: A custom extension that replaces single image tags with a set of optimized images using srcset. For more information, see the Optimized Images documentation.

#HeadingPermalinkExtension Options

The configuration also includes options for the HeadingPermalinkExtension:

 1'config' => [
 2    'heading_permalink' => [
 3        'html_class' => 'mr-2 scroll-mt-12',
 4        'id_prefix' => 'content',
 5        'apply_id_to_heading' => false,
 6        'heading_class' => '',
 7        'fragment_prefix' => 'content',
 8        'insert' => 'before',
 9        'min_heading_level' => 2,
10        'max_heading_level' => 3,
11        'title' => 'Permalink',
12        'symbol' => '#',
13        'aria_hidden' => true,
14    ],
15],

These options control how heading permalinks are generated and styled in the rendered HTML.

#Image Optimization

The last section of the configuration file deals with image optimization settings:

1'image' => [
2    'widths' => [
3        480, 640, 768, 960, 1536,
4    ],
5    'sizes' => '92vw, (max-width: 1024px) 92vw, 768px',
6],
  • widths: Specifies the widths to be used in the srcset for responsive images.
  • sizes: Provides the sizes attribute to be included in the image tag in your final HTML markup.

For more information on how Prezet optimizes images, see the Optimized Images article.

#Additional Customizations

Prezet offers various customization options beyond the configuration file. Here are some additional resources for customizing different aspects of Prezet:

These articles will guide you through the process of tailoring Prezet to your specific needs.