Query Markdown Content with Eloquent in Laravel: Filtering, Sorting, and Pagination

The developer behind the open-source Fusion package released a Laravel library that exposes Markdown files with YAML Frontmatter as Eloquent models, letting developers filter, sort, and paginate file-based content with familiar methods like where(), orderBy(), and paginate(). Fusion parses Frontmatter into model attributes, derives slugs from filenames unless overridden, and adds caching plus a fusion:check --validate command for enforcing Frontmatter rules. The package targets documentation and knowledge collections that need querying by metadata such as section or order.

Markdown is common in documentation, project knowledge bases, website content, and instructions for AI coding tools. If your code needs to load one Markdown file and already knows its path, that is straightforward. The challenge appears when content becomes a collection, for example, documentation split across many chapter and section files. Markdown describes the body of each file, but a collection also needs structured information to identify and organize its content. A common way to add it is YAML Frontmatter: a small block at the beginning of a Markdown file, enclosed by --- , with fields such as title , section , order , or published . For example, section: installation lets the application identify which part of the documentation a file belongs to, while order: 2 can define its position within that section. Once files have this metadata, the application needs a way to query it, to retrieve the whole collection or a relevant subset, such as all installation sections or the chapters in one guide, sorted in the intended order. Without a query layer, the application has to scan files, parse Frontmatter, and implement filtering and sorting itself. Fusion gives Laravel developers a familiar way to work with that content. It exposes Markdown files as Eloquent models, so you can use the same methods you already know from database-backed models where , orderBy , and paginate without learning a separate query API. Your Markdown remains the source of truth; Fusion handles parsing Frontmatter and rendering the content so you can retrieve it through Eloquent. This guide builds a practical article collection and shows how to configure its content folder, query it, and use Fusion's caching and content checks. Install Fusion with Composer: composer require hi-folks/fusion A simple content collection can live under resources/content/article . Each file contains YAML Frontmatter for structured values and Markdown for the body: --- title: Working with Markdown in Laravel date: "2026-10-19" published: true category: laravel excerpt: A practical guide to querying file-based content. --- Working with Markdown in Laravel This article is stored as a Markdown file and can be retrieved through Eloquent. Fusion uses each Markdown filename without its extension as the slug when the Frontmatter has no slug key. You can set a slug value in Frontmatter when the URL should differ from the file name. Avoid setting slug to an empty or null value: because the key is present, Fusion treats it as an explicit override instead of falling back to the filename. This format is useful when content should be reviewed in Git, edited with any Markdown editor, or kept alongside application code. It also works for curated documentation and knowledge collections, including material that developers or AI coding tools need to retrieve by category or metadata. Create a model for the article content directory and use Fusion's trait. The frontmatterFields method lists the Frontmatter keys that Fusion should load as model attributes: php <?php namespace App\Models; use HiFolks\Fusion\Traits\FusionBaseModelTrait; use Illuminate\Database\Eloquent\Model; class Article extends Model { // Loads Markdown-backed content rows into this Eloquent model. use FusionBaseModelTrait; // List the Frontmatter keys Fusion should expose as model attributes. public function frontmatterFields : array { return 'title', 'date', 'published', 'category', 'excerpt', ; } // Cast values when accessed as attributes; casts do not validate Frontmatter. protected function casts : array { return 'date' = 'date:Y-m-d', 'published' = 'boolean', ; } // Used by fusion:check --validate to check each file's Frontmatter values. public function frontmatterRules : array { return 'title' = 'required', 'string', 'max:255' , 'date' = 'required', 'date' , 'published' = 'required', 'boolean' , 'category' = 'required', 'string' , 'excerpt' = 'nullable', 'string' , ; } } Fusion reads the model's content directory and builds Eloquent records from the files. Frontmatter becomes attributes, the Markdown body is rendered to HTML in the body attribute, and each record includes path information. The source content remains in Markdown; Fusion does not require you to store it in your application's database. The casts shown above make attribute access convenient. For example, $article- date is returned as a Carbon date and $article- published as a boolean. Casts do not define query rules or make fields required. Keep date values in a consistent sortable format, such as YYYY-MM-DD , when ordering by the raw date field. Once the model is configured, retrieval looks like a normal Eloquent query: php use App\Models\Article; // Keep published articles in selected categories, newest first, 12 per page. $articles = Article::query - where 'published', true - whereIn 'category', 'laravel', 'php' - orderByDesc 'date' - paginate 12 ; This query filters out drafts, keeps articles in either the Laravel or PHP category, sorts the results newest first, and returns twelve per page. The fields used in queries—here published , category , and date —must be listed in frontmatterFields . You can combine these with familiar Eloquent methods such as where , orderBy , latest , and limit to shape the result set. For a detail page, retrieve one record by its slug: php // The filename is used only when Frontmatter has no slug key. $article = Article::where 'slug', $slug - firstOrFail ; Then render the stored HTML body in a Blade view: php <article <h1 {{ $article- title }}</h1 <time {{ $article- date- format 'F j, Y' }}</time {{-- Fusion renders Markdown as HTML; only output trusted or sanitized content. --}} <div class="prose" { $article- body } </div </article As with any rendered HTML, treat content as trusted or sanitize it according to your application's security requirements before outputting it unescaped. By default, Fusion looks under resources/content , using a subdirectory based on the model name. An Article model reads from resources/content/article , while a Page model reads from resources/content/page . This convention keeps content organized by type and requires little configuration. To keep content somewhere else—for example, alongside project documentation or in a shared content folder—set FUSION CONTENT DIRECTORY to the root directory containing the model-specific subdirectories: Relative to the Laravel app root; Fusion appends each model's subdirectory. FUSION CONTENT DIRECTORY=content/markdown Relative paths resolve from the Laravel application's base directory. With this setting, Article reads from content/markdown/article . Absolute paths are also supported. The configured directory is a shared root, and Fusion appends each model's folder name. This is the simplest option when all content should move together. If one model needs a uniquely named folder, override getResourceFolder in that model: public function getResourceFolder : string { // Use this model-specific folder instead of the shared root/model-name path. return base path 'docs/posts' ; } This gives that model a specific location without changing the shared root used by other models. The tradeoff is that the path is now part of the model code. Fusion uses Sushi to build a table per model class, so changing this path after the model's rows have loaded is not a supported way to switch folders at runtime. For one-off directory inspection, fusion:check --dir=... can target a folder without changing a model. When Fusion loads content rows, it parses Frontmatter and renders Markdown. For a large collection, repeating that work on every request can add overhead. The cache contains parsed content rows, including Frontmatter values and rendered body HTML. It does not cache the results of Eloquent filters or sorting. Fusion fingerprints the files to detect edits, additions, removals, and renames; even with a warm cache, it still scans and hashes the content files before it can reuse cached rows. Fusion automatically caches resolved content rows using Laravel's configured default cache store. Choose the store in Laravel's config/cache.php ; there is no separate Fusion setting to enable or disable row caching. Cached rows expire after one hour by default. Set the lifetime in seconds in config/fusion.php or with an environment variable: Row-cache lifetime in seconds 7200 seconds = two hours . FUSION CACHE TTL=7200 This sets the cached row lifetime to two hours. The fingerprinting means caching is most useful when the same collection is loaded repeatedly, especially when parsing and Markdown rendering are significant parts of request work. It does not remove the cost of the Eloquent query itself. The fusion:check command can inventory Frontmatter fields before you finish a model. Deep validation also checks Frontmatter parsing and Markdown rendering: Deep-check Frontmatter parsing and Markdown rendering. php artisan fusion:check --validate When the model defines a frontmatterRules method, Fusion can validate each file's Frontmatter using Laravel's validation rules. Unknown Frontmatter keys can be reported as warnings with --warn-unknown-fields . For CI, JSON output is easier to process, and changed-file checking can limit work to files in a pull request: Validate changed content since the base ref, including schema and unknown-field checks. php artisan fusion:check \ --validate \ --changed \ --base="origin/main" \ --model="App\Models\Article" \ --warn-unknown-fields \ --format=json This is useful when a repository has many Markdown files but a change touches only a few. The check can report invalid content before it is merged without requiring a full scan on every pull request. Make sure the base ref is available in the CI checkout; for GitHub Actions, use sufficient history for example, fetch-depth: 0 or fetch the base branch before running the command. Fusion keeps the content authoring format simple while exposing the retrieval patterns Laravel developers already know. Teams can review Markdown changes in Git, use Frontmatter to describe structured content, and filter or sort records with Eloquent instead of building a separate content-query layer for every application. The package also keeps those concerns separate: Laravel casts shape values when attributes are accessed, Laravel validation rules define which Frontmatter values are acceptable, Fusion handles parsing and rendering, and Eloquent handles querying. That makes the content workflow easier to understand and extend. Fusion lets Laravel applications keep Markdown as the content source while using Eloquent to filter, sort, and paginate it. Teams can describe content fields on a model and use familiar Laravel tools for caching and validation, without building a separate query layer or moving the source content into a database.