Metalsmith Blog Lists

A metalsmith plugin to provide various blog lists

Features

The plugin adds the following lists to the metadata to enable various blog widgets on any page.

• All Blogs
• Recent Blogs
• Featured Blogs
• Annualized Blogs List

The following properties must be defined in the frontmatter:

post:
  title: 'Post Title'
  excerpt: 'A brief description of the post'
  date: '2024-01-15'
  author: 'Author Name'
  image: '/images/post-image.jpg'

post is the default name of the blog properties object. It may be changed by setting the blogObject option.

The lists may be used to show all blog posts by a particular author.

All Blog Posts

The plugin provides array allSortedBlogPosts, sorted by date. It can be used when the whole list of blog posts is not available, for example, when using pagination, NOT all blog posts are available on a paginated page.

Latest Blogs

The plugin provides array latestBlogPosts. The number of blog posts listed is determined by option latestQuantity.

Featured Blogs

The plugin provides array featuredBlogPosts. Blog posts can specify, in their Frontmatter, that the post be listed and in what position of the list.

Annualized Blogs List

The plugin provides an associative array annualizedBlogPosts. All blog posts are listed by their creation year.

Nested Blog Properties

The plugin also supports getting blog properties from a nested object in your frontmatter. This is useful when you want to organize your blog-related properties under a single object. For example:

---
title: 'Page Title' # Regular page title
blog:
  title: 'Blog Post Title' # Blog-specific title
  excerpt: 'This is the blog excerpt'
  date: '2023-01-15'
  featuredBlogpost: true
  featuredBlogpostOrder: 1
---

To use this structure, set the blogObject option to the name of the nested object (e.g., "blog"). The plugin will first look for properties inside that object and fall back to direct properties if not found.

Installation

NPM:

npm install metalsmith-blog-lists

Yarn:

yarn add metalsmith-blog-lists

Usage

For blogs intended to be featured, add the following fields to their frontmatter:

---
featuredBlogpost: true
featuredBlogpostOrder: <integer>
---

Pass metalsmith-blog-lists to metalsmith.use :

ESM (ES Modules)

import blogLists from 'metalsmith-blog-lists';

metalsmith.use(
  blogLists({
    latestQuantity: 4,
    featuredQuantity: 2,
    featuredPostOrder: 'desc',
    fileExtension: '.md',
    blogDirectory: './blog',
    blogObject: '' // For nested blog properties (e.g., thisFile.blog.title), use "blog"
  })
);

CommonJS

const blogLists = require('metalsmith-blog-lists');

metalsmith.use(
  blogLists({
    latestQuantity: 4,
    featuredQuantity: 2,
    featuredPostOrder: 'desc',
    fileExtension: '.md',
    blogDirectory: './blog',
    blogObject: '' // For nested blog properties (e.g., thisFile.blog.title), use "blog"
  })
);

Options

Option	Type	Default	Description
latestQuantity	Number	3	The number of latest blog posts to display
featuredQuantity	Number	3	The number of featured blog posts to display
featuredPostOrder	String	'desc'	The order in which featured blog posts are displayed: "asc" or "desc"
fileExtension	String	'.md'	The file extension of blog posts
blogDirectory	String	'./blog'	The path relative to the Metalsmith source directory containing the blog posts (e.g., "./blog", "./content/blog")
blogObject	String	'post'	The name of the blog object in frontmatter for nested properties (e.g., "post" for thisFile.post.title)
usePermalinks	Boolean	true	When true, file paths will have extensions removed (e.g., '/blog/post'). When false, .md extensions will be replaced with .html (e.g., '/blog/post.html')

Note: The blogDirectory option supports both root-level blogs ("./blog") and subdirectory blogs ("./content/blog"). Always include the relative path prefix ./.

Note: The blogObject option lets you work with nested blog properties in your frontmatter. When set to a non-empty string (e.g., "blog"), the plugin will look for properties inside that object (e.g., thisFile.blog.title). If not found or if blogObject is empty, it falls back to direct properties (e.g., thisFile.title).

Examples

Using a Nunjucks template

Display an annualized blog archive

{% for theYear in annualizedBlogPosts %}
  {{theYear.year}}
  <ul>
  {% for post in theYear.posts %}
    <li>
      <a href="/{{post.path}}">{{post.title}}</a>
      <p>{{post.date}}</p>
      <p>{{post.author}}</p>
    </li>
  {% endfor %}
  </ul>
{% endfor %}

Display a featured blog list

<ul>
  {% for post in featuredBlogPosts %}
  <li>
    <a href="/{{post.path}}">{{post.title}}</a>
    <p>{{post.date | blogDate}}
    <p>{{post.author}}</p>
  </li>
  {% endfor%}
</ul>

Debug

To enable debug logs, set the DEBUG environment variable to metalsmith-blog-lists:

DEBUG=metalsmith-blog-lists

CLI usage

To use this plugin with the Metalsmith CLI, add metalsmith-blog-lists to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "metalsmith-blog-lists": {
        "latestQuantity": 4,
        "featuredQuantity": 2,
        "featuredPostOrder": "desc",
        "fileExtension": ".md",
        "blogDirectory": "./blog",
        "blogObject": ""
      }
    }
  ]
}

Test Coverage

This project maintains high statement and line coverage for the source code. Coverage is verified during the release process using the c8 coverage tool.

Author

werner@glinka.co

License

ISC