October 03, 2017

Generate a static markdown blog using Vuelog

by Connor Leech

generate-a-static-markdown-blog-using-vuelog

In this tutorial, we are going to go through cloning and setting up a static blogging application with Vuelog. Vuelog is built out of Vue.js and uses the marked markdown parser in addition to Vuex, Vue-router and a global database object to store configuration about our blog. This is an impressive Vue.js project utilizing some of the latest technologies. In this post, we will go through some aspects of the code and configure the project to meet our own ends.

Demo: http://connorleech.info/vuelog-starter/
Source code: https://github.com/JscramblerBlog/vuelog-starter.

Disclaimer

This tutorial is written specifically for those interested in utilizing Vue.js for their client-side blogging needs. Vue.js is an open source Javascript library for building client rich UI applications. There are plenty of more developed Javascript static blogging tools (such as Hexo or Wintersmith) though relatively few written in Vue.js. This tutorial focuses on Vuelog because Vuelog is written in Vue.js. After analyzing Vuelog we are free to build our own static site generator, look for alternatives or adopt and modify it for our own ends. Whatever we choose, the goal of this post is to make us better Vue.js developers by looking at a real world project and the use case for static blogging.

To start off with: Project Structure

The first thing I noticed about Vuelog was that it does not come with tools for programmers to quickly or easily generate new applications or swap out themes. Many of its competitors in this space, such as Hexo come with tools for generating fresh applications and configuration options for swapping out community built themes. Vuelog is more of a project than a framework so in order to build our own Vuelog we’ll have to go through the age old process of forking and cloning the repo. This leaves a lot to be desired in terms of getting started quickly, but nevertheless gets us up and running with a static blog boilerplate made primarily of Vue.js and Javascript.

Once we fork and clone the repo we have the following project structure:

/build
    ...webpack and vue loader build process files
/config
   ... environment configuration files
/docs
   …all of the projects documentation
/src
   /assets
   /components
   /helpers
   /i8n
   /router
   /store
   /views
   main.js
    Vuelog.vue
/static
/test
   /e2e
   /unit
/userdata
   /images
   /pages
   /posts
   database.js
index.html  
package.json  

There are some additional hidden files but this is the meat and potatoes of the application. As you can see we have an extensive project already built with Vue.js. The key folders to note here are the userdata and src folders. The src folder contains all of the Vue.js project, routing logic and store information. userdata is where we store our blog posts, define the pages of our application and configuration options within the database.js file.

Internationalization

One major strength of the Vuelog project for static blogging (outside of the fact that it is built with Vue.js) is that the project takes internationalization very seriously. The project creator (@myst729) is from China and has the documentation and blog posts are available in Chinese and English. To handle the internationalization heavy lifting Vuelog uses the vue-i18n package.

Post structure

In order to generate a new post on our blog, we can utilize the following structure.

title: This is a sample title  
category: docs  
date: 2017-09-22  
------------------------------------
<!-- en-US:+ -->  
English **markdown** content goes here  
<!-- en-US:- -->

<!-- zh-CN:+ -->  
Chinese language content goes here

<!-- zh-CN:- -->  

The above comments specify i18n language codes to render the appropriate content.

This file goes in the userdata/posts/2017 directory. In order to render the post we must specify the post meta details in userdata/database.js:

  posts: [
    /* 2017 */
    {
      title: {'en-US': 'This is a sample title'},
      slug: 'sample',
      category: 'docs',
      date: '2017-09-22'
    },
    ...

Once we have the post created and the configuration object in our database.js file we can view it in the browser by running npm run dev. The application will run on http://localhost:8080.

Vuelog starting point

This is great for rendering our blog posts. We can easily add content with categories, markdown and configuration options without having to write application logic. Since this project was forked though we’re going to need a way to modify the rest of the blog including the navigation, pages, images, and copy.

Configuration: The database.js file

Using userdata/database.js we can specify a config object to update things like the title and feature image:

window.VUELOG_DATABASE = {  
   config: {
      // The name of your site, will be displayed in browser tab and site header.
       brand: {'en-US': 'My first Vuelog'},

       // The image displayed in site header right beside the brand.
       logo: './static/employbl_logo.png',
      ...

The VUELOG_DATBASE will be mapped to database in our Vue.js application code (located in the src directory) through webpack. This configuration file provides a convenient way to access variables within Vue.js code.

Additionally, in the database.js file, we can specify the navigation fields like so.

navigation: [  
    {
      label: {'en-US': 'Work' },
      type: 'page',
      path: '/page/work'
    },
    {
      label: {'en-US': 'About' },
      type: 'page',
      path: '/page/about'
    },
    {
      label: {'en-US': 'Blog' },
      type: 'category',
      path: '/blog'
    },
    {
      label: {'en-US': 'Archive' },
      type: 'archive',
      path: '/archive'
    },

The blog and archive URLs are built already out of the box. To have custom pages such as Work we have to create the corresponding file in userdata/pages/work.md.

Conclusion

In this article, we’ve outlined the structure of a static blog cloned from Vuelog. We have added a post, updated configuration information, customized the navigation and added pages. The underlying structure of Vuelog is configurable through the userdata folder. Vuelog lacks robust tools for theming or generating apps from the command line. It does have a solid focus on internationalization for curating our blog to different language speakers. In order to further modify a Vuelog blog, we’ll need to dive into the Vuelog source code and familiarize ourselves with Vuex for managing the application state. I hope this tutorial introduced you to the possibilities of static blogging with Vuelog and how quick we can get up and blogging with Vue powered tools.