Ever since I started looking at web development, I’ve had a thing for static site generators. They are a great way to get a simple website up and running. I’ve used many of the currently available generators: Jekyll, Hugo, Hexo. I’m always trying to learn the different features and why one is better than the other.

A new player has entered the SSG scene, VuePress. VuePress is built using the up and coming javascript framework Vue.js. This allows you to use all of the features of Vue.js while creating your static website. Tie that with an extremely easy setup and you’ve got a simple and powerful website generator.

Creating a VuePress project

Create the root directory of your project and change to that directory.

1

mkdir <myproject> && cd <myproject>

Install the VuePress library locally using yarn.

1

yarn add vuepress

From here you can create a folder structure for organizing your information. VuePress will follow your folder structure and use the same paths for the urls of your website. This is one of the features that makes VuePress easy to use. The following are some example file paths and their equivalent URLs.

./README.md -> /

./posts/README.md -> /posts/

./posts/top-10-winter-car-memes.md -> /posts/top-10-winter-car-memes.html

Be sure to use the full paths for your urls. /post loads a blank white page. /posts/ is a page with the content of /posts/README.md displayed.

At this point you should have a basic working website using the default theme. You can start the development server by navigating to your root directory and running:

1

vuepress dev

Navigate to localhost:8080 and you will be able to see a page for each of the pages you added to your project. If you would like the website to be built hosting you can use:

1

vuepress build

Adding configuration files

There are two locations that are important when it comes time to customize your website. The first is the config.md file in the root of your project. This is where you put basic information about your website that can be pulled into the pages such as the title and author. An example of this file might look like the following.

1
2
3
4

module.exports = {
  title: "NixStuff",
  description: "A place for my stuff"
};

The next important location is your .vuepress folder. Everything within this folder is optional but this is where you can really get into advanced customization of your website. The contents are further broken down into the following folders and files.

  • components - Here you can put your own custom Vue components that are automatically registered as global and usable within your markdown files.
  • theme - If you’re not interested in customizing your entire website yourself, you can add a premade theme to this directory that VuePress will use to generate your site
  • public - A directory for static resources such as photos.
  • styles - VuePress uses .style files to customize the style of the pages rather than css. These files are stored within this folder.
  • templates - A location to store premade templates so that VuePress knows how your content should be displayed on a page.
  • config.js - Entry point of the website’s configuration
  • enhanceApp.js - Used for app level enhancements. This is where you can add things such as third party libraries for Vue to use.

VuePress is a great looking up and coming static site generator. I’m especially drawn to it do to how much I’ve enjoyed use the Vue.js framework. It’s still very young in its development and may not be the best for a production website but I could see it being a major contender down the road.

Hosting on Netlify

Netlify offers a great service for hosting a website. They’ve created an extremely easy setup process for static site generators. VuePress is no different. You will need to first add your website to a git repo through GitHub or GitLab.

You will then need to go to Netlify and create an account. After going through the sign up process, you should end up on your project dashboard. Click the button to create a new project and follow the creation instructions. The last page will ask for build commands and the project’s output folder. For VuePress you can use the following.

1
2
3

npm install && vuepress build

.vuepress/dist

Advanced Setup

Like anything in software, it is nice to be able to backup your working using source control. This can be achieved by adding a netlify.toml file to the root of your project. This file allows you to pass build commands and build environment information to the Netlify build system from the netlify.toml file. The settings in this file will override the settings entered through the Netlify UI. A basic netlify.toml file might look like the following:

1
2
3
4
5
6
7

[build]
    command = "yarn install && yarn build"
    publish = ".vuepress/dist/"

[build.environment]
    NODE_VERSION = "8"
    YARN_VERSION = "1.6.0"

After this you should have your website up and running. Your Netlify dashboard will provide the link to your website in the form of <project name>.netlify.com.