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.
Organize content as Markdown files
Install Fusion with Composer:
composer require hi-folks/fusion
Here is the GitHub repository of Fusion: https://github.com/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.
Connect the directory to an Eloquent model
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
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.
Filter, sort, and paginate with Eloquent
Once the model is configured, retrieval looks like a normal Eloquent query:
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:
// 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:
<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.
Choose where content lives
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.
Cache parsing and rendering work
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.
Check content during development and in CI
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.
Why this approach fits Laravel projects
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.
Conclusion
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.
