Middleman Integration Guide

This guide provides resources and information for integrating Sveltia CMS with Middleman, a static site generator using Ruby.

Examples

See real-world examples of Middleman integrations in our Showcase. Most of the listed sites include links to their source code, so you can explore how they implemented Sveltia CMS with Middleman.

Setup

Adding the Admin Page

All the files that make up a Middleman site live in the source folder. Create source/admin/index.html and source/admin/config.yml as described in the Getting Started guide.

Middleman applies the site layout to every HTML file in the source folder, which would break the admin page. Turn off the layout for the admin folder in config.rb:

page '/admin/*', layout: false

The admin page is then available at /admin/ on the development server started with middleman server as well as on the built site.

Configuration

Blog posts are usually managed with the middleman-blog extension. Its sources option defines the file name pattern for posts, which includes the post date by default:

activate :blog do |blog|
  blog.prefix = 'blog'
  blog.sources = '{year}-{month}-{day}-{title}.html'
end

With this configuration, posts are stored in source/blog with names like 2026-10-01-hello-world.html.md. The matching Sveltia CMS entry collection needs three options to follow the pattern:

• slug creates the date prefix from the slug template tags {{year}}, {{month}} and {{day}}, which are based on the entry creation date.
• extension is set to html.md, because Middleman uses the double extension to determine the output format (html) and the template engine (Markdown).
• format is set to frontmatter so the files are read as Markdown with front matter despite the custom extension.

media_folder: source/images/uploads
public_folder: /images/uploads
collections:
  - name: blog
    label: Blog
    folder: source/blog
    slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
    extension: html.md
    format: frontmatter
    create: true
    fields:
      - { name: title, label: Title }
      - { name: tags, label: Tags, widget: list, required: false }
      - { name: published, label: Published, widget: boolean, default: true }
      - { name: body, label: Body, widget: markdown }

title is the only required front matter property in middleman-blog, and posts with published: false are treated as drafts that only appear on the development server.

The post date is taken from the file name. If you also want editors to set the date, add a DateTime field named date and build the slug from it with the date transformation, so the file name follows the selected date instead of the creation date:

slug: "{{date | date('YYYY-MM-DD')}}-{{slug}}"

Keep in mind that middleman-blog stops the build if the date in the front matter doesn’t match the one in the file name. The file name is set when a post is first saved, so if an editor changes the date of an existing post, they also need to update the date in the slug from the Slug panel, which renames the file.