I Built a Laravel Blog Package That Uses Markdown Files Instead of a Database

I've been building Laravel apps with Inertia frontends, and every time I needed a blog, I'd reach for a CMS. WordPress, Ghost, headless options — they all work, but they felt heavy for what I actually needed.

So I built https://github.com/jcfrane/laravel-md-blog — a Laravel package that lets you write blog posts as plain markdown files with YAML front matter. No database, no admin panel, no rich text editor. Just files.

How It Works

Drop .md files into resources/markdown/blog/:

---
title: My First Post
date: 2026-03-01
tags: [laravel, php]
category: tutorials
excerpt: A quick intro to my blog.
---

# My First Post

Your content here. Supports **bold**, *italic*, tables,
task lists, and everything else in GitHub Flavored Markdown.

Then query them with a clean API:

use JCFrane\MdBlog\Facades\MdBlog;

// All published posts, newest first
$posts = MdBlog::latest();

// Single post
$post = MdBlog::find('my-first-post');

// Filter
$posts = MdBlog::whereTag('laravel');
$posts = MdBlog::whereCategory('tutorials');

That's it. Every method returns Laravel Collections, and the Post object implements Arrayable and JsonSerializable — so passing it to an Inertia response just works:

return Inertia::render('Blog/Show', [
    'post' => MdBlog::find($slug),
]);

Why Not Just Use a CMS?

For developer blogs on Laravel apps, a CMS adds a lot of overhead:

• Another database table (or an entire separate system)
• An admin panel to build and secure
• Rich text editors that produce unpredictable HTML
• Deployment complexity for something that changes once a week

With markdown files, your editor is your CMS. Git is your version history. Your deploy pipeline publishes your posts.

The Caching Layer

I didn't want to parse markdown on every request, but I also didn't want stale content after editing a file. So the package caches each post individually and checks the file's modification time on every read. If the file changed, the cache entry is automatically refreshed. No manual cache busting needed (though MdBlog::clearCache() exists if you want it).

Drafts

Set published: false in the front matter and the post is hidden from every query method. No separate drafts folder, no status column — just a boolean in the file.

What I Learned Building It

A few things stood out:

YAML date parsing is surprising. The spatie/yaml-front-matter package uses Symfony's YAML parser under the hood, which automatically converts date-like strings (2026-03-01) into Unix timestamps. Something to be aware of if you're writing tests against raw front matter values.

Theleague/commonmark is incredibly extensible. Adding GitHub Flavored Markdown support (tables, task lists, strikethrough, autolinks) was a single line — just register the GithubFlavoredMarkdownExtension. The environment/extension architecture makes it easy to add custom extensions later.

Try It Out

composer require jcfrane/laravel-md-blog

The source is on GitHub. It targets Laravel 12+ and PHP 8.2+.

If you're a developer who blogs about code, and you're already in your editor all day, writing posts in markdown files feels natural. Give it a shot.