Hello, blog!

Welcome to this blog post! It’s a short overview of some of this template’s main features.

The Middleman blog engine supports all the things you’d expect, like markdown files, frontmatter, tags and pagination (read more)

Markdown parsing

This template uses kramdown to parse markdown. It supports a bunch of handy things like:

Frontmatter

Middleman supports frontmatter in markdown pages by placing a block of YAML at the start of a document, like this:

---
title: A page
date: 2024-05-03
---

Frontmatter can be accessed using Ruby code via current_page.data.title, .date etc. It’s automatically used by the _head_meta_tags.html.erb partial to generate HTML <meta> tags.

Blog pages require a title: and date: to be provided, and also support description:. Other markdown pages (ie: about.html.md) only require title: with an optional description: —

---
title: Blog page (source/blog/example.html.md)
date: 2024-05-03
description: Optional
---
title: Regular page (source/about.html.md)
description: Optional
---

Images & captions

This is a caption.

Render an image caption by including some italic text on the same line as your image:

![Pencil](images/pencils.png){:class="max-w-xs"} _We've even got images & captions!_

Within main.css I’ve included a custom CSS selector to target that text and make it appear as a caption:

#prose-content > p > img + em {
  @apply text-stone-500 text-sm;
}

Table of contents

You can natively generate a table of contents (thanks to kramdown) that looks like this:

Here’s the code:

<details>
<summary>Table of Contents</summary>
<aside markdown="1">
* seed list
{:toc}
</aside>
</details>

Unfortunately, Middleman doesn’t seem to support partials in .html.md files, so if you want a table of contents, you have to copy that code from file to file.

Blog configuration

Towards the start of config.rb you’ll see this:

activate :blog do |blog|
  ...
end

This is configuration for the middleman-blog extension, which powers the blog engine of this template.

The result is that if you add a new .html.md file to the source/blog directory, it will get picked up by Middleman and rendered on the index page. It’s rendered into the layouts/markdown_layout.erb layout, which also displays the menu and applies the TailwindCSS prose class to the output.

Read more: Blogging with Middleman