README

Mezzio Markdown Blog

This is a basic blog module for Mezzio applications, allowing you to get up and running with a blog in your applications pretty quickly.

How it works

When installed, the module adds two routes to the application's routing table.

One to list all of the available blog items

Using the path /blog[/{current:\d+}], by default it lists the first page of the blog index. However, if a page number is supplied current, then that page of the blog will be displayed. Alternatively, the user can move forward and backward through pages of the blog by using the pagination links at the bottom of the current page. It converts a series of Markdown files with Yaml front-matter into an array of BlogArticle entities, which are then rendered as HTML.

One to view individual blog items

Using the path /blog/item/{slug}, this route displays a blog item with the slug provided. In addition to being able to view the matching blog item, a listing of one or more blog items that are related to the current item are also available, if any matches are available.

What do the Markdown files look like?

Here is a sample article, so that you know, roughly, what to expect.

---
publish_date: 13.07.2025
slug: episode-0001
synopsis: In this blogArticle, I have a fireside chat about one of my all-time favorite books, The Mythical Man Month.
title: Talking about The Mythical Man Month.
categories:
  - software development
tags:
  - Books
  - Mythical Man Month
---

### Synopsis

Suspendisse viverra mauris ac urna gravida, vel malesuada dolor interdum. Nullam ultrices urna erat, non venenatis turpis placerat eget. Etiam vitae magna non tortor congue volutpat. Integer ut ornare ante. Etiam hendrerit vehicula turpis, sit amet pulvinar nunc dictum eu. In tincidunt sollicitudin eros, quis ultrices turpis maximus ut. Ut eu erat eget magna congue ornare vel et tortor. Curabitur laoreet neque et ex aliquet tempus.

### Related Links

- [The Mythical Man Month (on Wikipedia)][mythical-man-month-book-url]

Usage

The package is designed to be used as part of Mezzio-based applications, and goes to a lot of effort to make doing so as simple as possible.

Install the package

To install the package, use Composer (just as you would install any other package) by running the following command:

composer require settermjd/mezzio-markdown-blog

During installation, the project's ConfigProvider will be loaded into config/config.php, loading all of the required dependencies, routes, and template paths. Given that, most of the work is done for you, including registering the routes and accompanying handlers for:

Listing all blog articles (the blog index page) – with pagination. The route is /blog.
Viewing individual blog articles. The route is /blog/article/{slug}.

Set up the articles directory

There is no way to create the articles (posts) directory as part of the installation process, so you need to do this yourself. So, in the data directory, create a new directory named posts. The path needs to match the path element that you set in the application's configuration, outlined in the previous section.

Note

In a future version, there will be tooling to automate this.

Override the default templates

The next thing that you need to do is to override the blog templates. There are default versions in the project's templates/blog directory. But these are quite generic and only meant as a way of quickly getting you started. They're not designed to be a professional design for every application.

The three templates are:

blog.html.{{your view renderer extension}}. This template is the blog index page that renders all of the available articles or posts for your blog.
blog-article.html.{{your view renderer extension}}. This template renders details of a specific blog post when it is viewed.
includes/pagination.html.{{your view renderer extension}}, e.g., includes/pagination.html.twig. This is the pagination template which is called by the blog index template, so that users can step through the available blog records a page at a time.

Note

There are three versions of each template:

One for Twig
One for laminas-view
One for Plates

Update the application's configuration (optional)

If you want or need to, you can also update the module's configuration as well.

By default, its configuration is set in Settermjd\MarkdownBlog\ConfigProvider. However, you can override this by copying the default configuration file, config/autoload/blog.local.php to the application's config/autoload directory. You can find documentation for each option in both the config file and in Settermjd\MarkdownBlog\ConfigProvider.

When using Twig as your view renderer

If you use Twig as your view renderer, while you don't need to, you can create more feature-rich templates by installing PHP's Intl extension, and the twig/markdown-extra and twig/intl-extra packages.

After installing PHP's Intl extension using your package manager or from source, install the two Twig packages using the following command:

composer require twig/intl-extra twig/markdown-extra

settermjd / mezzio-markdown-blog

Maintainers

Details