Postlist

Postlist is a Micro.blog plugin that will add a short-code allowing you to a list of posts to a page, similar to Bear blog’s posts macro. The list of posts can be filtered to those of a specific category, and displayed either in chronological or alphabetical order.

Usage

Once installed, a post list can be added to a post or page by using the following short-code:

{{< postlist >}}

This will produce a list of all posts — both with and without titles — ordered in reverse chronological order.

Filtering By Category

Use the categories attribute to only show posts that match a given category:

{{< postlist categories="Cheatsheet" >}}

Category names are case sensitive, and must match the name of the category as entered in Micro.blog. Multiple categories can be specified with commas, and a post must be in each one in order to appear in the post list.

{{< postlist categories="Cheatsheet,Git" >}}

Ordering

By default, post lists are appear in reverse chronological order (newest posts appears on the top). If you want to use a different ordering, you can set the order attribute. This attribute value takes an ordering criterium and an optional direction. The supported ordering criteria are:

• alpha — order posts alphabetically, in ascending order (from A-Z). For those that are familiar with Hugo templates, this uses link title ordering, which loosely corresponds with the title, or the first few words of a titleless post.
• date — order posts based on post date, in ascending order (from oldest to newest).

Example: ordering posts from A-Z:

{{< postlist order="alpha" >}}

The default sort order is always in ascending order. To sort in descending order, add desc after the criterium.

Example: ordering posts from Z-A:

{{< postlist order="alpha desc" >}}

Example: ordering posts in reverse chronological order:

{{< postlist order="date desc" >}}

Item Limit

By default all posts matching the category filter will be included in the list. To limit the maximum number of posts displayed, use the limit attribute:

{{< postlist limit="3" >}}

Displaying Full Content

A post list can be configured to display the full content of posts matching the category filter. This changes the post list to something closer to the archive page, with the full post title, summary, or body included, rather than just the title or the first line of the summary.

To enable full display of a post list’s content, set display to content:

{{< postlist display="content" >}}

See Styling for the generated markup for posts displayed in this mode.

The markup used for post lists displayed in full content mode can be customised via the following micro-hooks:

• partials/_postlist/post-content-before.html: will be called just before the wrapped <div>. This partial receives the entire post list as ., allowing this template to be used for things like table of contents.
• partials/_postlist/post-content.html: will be called for each post item matching the filter.
• partials/_postlist/post-content-after.html: will be called just after the wrapped </div>. This partial receives the entire post list as ..

Styling

List Mode

Post lists are rendered as an unordered lists with the postlist class:

<ul class="postlist">
  <li><a href="...">Item 1</a></li>
  <li><a href="...">Item 2</a></li>
</ul>

The default CSS sets the list style to none and removes the leading padding, but otherwise keeps the list unstyled. Post lists can therefore be restyled by adding a ul.postlist CSS rule.

Full Content Mode

Post lists with display="content" mode will be rendered within a wrapping div, with each item wrapped in a separate div item. The wrapping div will have the classes postlist and postlist-display-content to identify the subtree as being a list of posts with full content. The wrapping div and items are also annotated with the h-feed microformat.

<div class="postlist postlist-display-content h-feed">
  <div class="h-entry">
    <h2 class="p-name"><a href="...">Title, if any...</a></h2>
    <div class="p-summary"><p>Summary, if any...</p></div>
    <div class="e-content">Content...</div>
  </div>
  <div class="h-entry">
    ...
  </div>
</div>

Feedback

Any feedback — bugs, feature suggestions, etc. — on this plugin is welcomed. Probably the best place to raise them is by creating an issue on GitHub. Alternatively, you can hit me up on Micro.blog.