metalsmith-blog-lists
v1.3.0
Published
A Metalsmith plugin to add blog lists to metadata.
Downloads
8
Maintainers
Readme
Metalsmith Blog Lists
A metalsmith plugin to provide various blog lists
This plugin requires all blogposts to be located in blog/
of the content directory.
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 data is available for each blogpost:
- Title
- Date
- Author
- Path
- Image
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.
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
:
const blogLists = require('metalsmith-blog-lists')
metalsmith.use(blogLists({
latestQuantity: 4,
featuredQuantity: 2,
featuredPostOrder: "desc",
fileExtension: ".md.njk",
blogDirectoryName: "blog"
}))
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>
Options
You can pass options to metalsmith-blog-lists with the Javascript API or CLI. The options are:
- latestQuantity: optional. The number of blogposts to display. The default is 3.
- featuredQuantity: optional. The number of featured blogposts to display. The default is 3.
- featuredPostOrder: optional. The order in which featured blogposts are displayed. The default is "desc".
- fileExtension: optional. The blogpost file extension. The default is
.md
. - blogDirectoryName: optional. The blogpost directory must be in the Metalsmith source directory.The default is
blog
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/metalsmith-blog-lists": {
"latestQuantity": 4,
"featuredQuantity": 2,
"featuredPostOrder": "desc",
"fileExtension": ".md.njk",
"blogDirectoryName": "blog"
}
}
]
}