Vuepress is an up and coming static site generator based on the Vue.js framework. Plugin support was added in version 1.x and there are already a number of functional plugins. Many of these plugins are still lacking in documentation and required troubleshooting to get them working correctly. Example repos were created for a number of the plugins and shared back with the Vuepress community.

The blog Plugin

The blog plugin makes it easy to sort and filter the different posts according to their tag and category frontmatter. Tag and Category variables are created containing information from all of the posts containing that tag or category. A custom component can then be created to use this information and render it on the page. The example project can be found below.

vuepress-blog-example

Once the plugin is installed, it will automatically search the layouts folder for layouts named Categories.vue, Category.vue, Tags.vue, and Tag.vue. The Categories and Tags layouts can be used to group all of the pages according to their categories or tags. The Category and Tag layouts will be used to display pages for an individual topic.

The back-to-top plugin

The back-to-top plugin adds an arrow at the bottom of a post to return the user to the top of the page. This plugin works with the default Vuepress style without needing any special configuration. The example project for this plugin shows how the style of the arrow can be overridden to match the theme it’s being used with.

vuepress-back-to-top-example

The pagination plugin

The pagination plugin splits posts in to groups of 10 for each page. A separate pagination variable becomes available with links to the next and previous pages of posts.

vuepress-pagination-example

While working, I found a number of gotchas while setting up the plugin. The plugin is currently hardcoded to only paginate posts found in the project’s page folder, only in groups of 10, and the default filter removes all posts. The first two issues were something I just had to live with. The last issue made the plugin unusable. Luckily, the filter can be overroad in the config.js settings of the plugin. I got it working by removing an extra set of parentheses in the default postsFilter.

1
2
3

{
  postsFilter: type => type.frontmatter.type === "post";
}

The resulting pages can be seen at /page/ and /page/#.

Summary

Vuepress is still considered a very alpha project. While there a many plugins and they generally work, they are usually lacking documentation for their usage. Hopefully this post helps to shine some light on the issues mentioned with using Vuepress plugins.