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-configAfter installation the configuration file will look like this:
1<?php 2 3return [ 4 /* 5 |-------------------------------------------------------------------------- 6 | Filesystem Configuration 7 |-------------------------------------------------------------------------- 8 | 9 | This setting determines the filesystem disk used by Prezet to store and 10 | retrieve markdown files and images. By default, it uses the 'prezet' disk. 11 | 12 */ 13 14 'filesystem' => [ 15 'disk' => env('PREZET_FILESYSTEM_DISK', 'prezet'), 16 ], 17 18 /* 19 |-------------------------------------------------------------------------- 20 | Data Classes 21 |-------------------------------------------------------------------------- 22 | 23 | These classes are used to store markdown information in a Validated DTO. 24 | You can override the default classes with your own and configure Pezet to 25 | use them here. 26 | 27 */ 28 29 'data' => [ 30 'frontmatter' => BenBjurstrom\Prezet\Data\FrontmatterData::class, 31 ], 32 33 /* 34 |-------------------------------------------------------------------------- 35 | CommonMark 36 |-------------------------------------------------------------------------- 37 | 38 | Configure the CommonMark Markdown parser. You can specify the extensions 39 | to be used and their configuration. Extensions are added in the order 40 | they are listed. 41 | 42 */ 43 44 'commonmark' => [ 45 46 'extensions' => [ 47 League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension::class, 48 League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkExtension::class, 49 League\CommonMark\Extension\ExternalLink\ExternalLinkExtension::class, 50 League\CommonMark\Extension\FrontMatter\FrontMatterExtension::class, 51 BenBjurstrom\Prezet\Extensions\MarkdownBladeExtension::class, 52 BenBjurstrom\Prezet\Extensions\MarkdownImageExtension::class, 53 ], 54 55 'config' => [ 56 'heading_permalink' => [ 57 'html_class' => 'prezet-heading', 58 'id_prefix' => 'content', 59 'apply_id_to_heading' => false, 60 'heading_class' => '', 61 'fragment_prefix' => 'content', 62 'insert' => 'before', 63 'min_heading_level' => 2, 64 'max_heading_level' => 3, 65 'title' => 'Permalink', 66 'symbol' => '#', 67 'aria_hidden' => false, 68 ], 69 'external_link' => [ 70 'internal_hosts' => 'www.example.com', // Don't forget to set this! 71 'open_in_new_window' => true, 72 'html_class' => 'external-link', 73 'nofollow' => 'external', 74 'noopener' => 'external', 75 'noreferrer' => 'external', 76 ], 77 ], 78 ], 79 80 /* 81 |-------------------------------------------------------------------------- 82 | Images 83 |-------------------------------------------------------------------------- 84 | 85 | Configure how image tags are handled when converting from markdown. 86 | 87 | 'widths' defines the various widths for responsive images. 88 | 'sizes' indicates the sizes attribute for responsive images. 89 | 'zoomable' determines if images are zoomable. 90 */ 91 92 'image' => [ 93 94 'widths' => [ 95 480, 640, 768, 960, 1536, 96 ], 97 98 'sizes' => '92vw, (max-width: 1024px) 92vw, 768px', 99 100 'zoomable' => true,101 ],102 103 /*104 |--------------------------------------------------------------------------105 | Sitemap106 |--------------------------------------------------------------------------107 | The sitemap origin is used to generate absolute URLs for the sitemap.108 | An origin consists of a scheme/host/port combination, but no path.109 | (e.g., https://example.com:8000) https://www.rfc-editor.org/rfc/rfc6454110 */111 112 'sitemap' => [113 'origin' => env('PREZET_SITEMAP_ORIGIN', env('APP_URL')),114 ],115 116];#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 options10],The included extensions are:
-
CommonMarkCoreExtension: Provides core CommonMark functionality.
-
FrontMatterExtension: Pulls the front matter from a markdown post for processing and SEO tag generation.
-
HeadingPermalinkExtension: Creates linkable headings in the body of the markdown content.
-
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.
-
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.