VuePress in all its glory

April 25, 2018 0 Comments

VuePress in all its glory

VuePress is a Vue-powered static site generator that is composed of two parts:

  1. A theming system
  2. A default theme optimized for writing technical documentation

Evan You, the creator of Vue,js, built VuePress to satisfy the documentation needs of various Vue-based projects.

One of the really cool things about VuePress is that it allows you to build a single-page application that has its own pre-rendered static HTML from a Markdown file that is powered by Vue, VueRouter, and Webpack.

There are several reasons to work with VuePress, but the ones that stand out are:

VuePress allows you to write Vue right inside the Markdown file. It’s able to do this because it compiles the Markdown file into HTML and processes them as a template in a Vue component.

VuePress supports some really great extensions that allow you to take writing in Markdown to the next level. For example,

YAML front matter: set predefined variables or create custom ones in your Markdown file and can be accessed using the$page variable in any file.

Header Anchors: automatically converts headers into anchor tags

Links: automatically convert links in Markdown into VueRouter’s <router-link> for SPA Navigation

Emoji: write Emojis in Markdown

Line Highlighting in Code Blocks: highlight a line of code in a Markdown code block

Table of Contents: tells the processor to pick all the header elements in the Markdown file and render them as a list of items with links.

To do this, you would have to write the tag below where you want it to render in the markdown file


GitHub-Style Tables: draw tables in Markdown.

VuePress comes with a fully responsive theme that has some little features already embedded such as header-based search, customizable navbar and sidebar, optional homepage, auto-generated Github link and Page edit links.

VuePress makes it easy to customize the default theme as well as create a completely custom theme.

VuePress has an option in the config that allows it to automatically generate and register a service worker that would cache the content for offline use.

VuePress also comes with integrated Google Analytics. To enable it, you have to add your Google Analytics ID in the config.

This one’s kind of self-explanatory, but it feels weird leaving an empty space.

There are two ways in which you can get started with VuePress:

  1. Installing it globally
  2. Adding it to an existing project

To install globally,

npm install -g vuepress

To add to an existing project

npm install -D vuepress

Once installation is done, we create our markdown file which is going to be the content of the static site and then run the code below to preview it.

vuepress dev

The VuePress setup already has hot reload enabled out of the box so as you are making changes to your markdown file, it automatically updates in your browser.

Looking at the preview in the browser, you would notice it’s pretty bald and almost none of the features mentioned exist yet.

To enable some of these features (homepage, sidebar, navigation etc), we need to create a config file.

This file is basically a JavaScript file that allows us to customize/enable or disable features in our project.

For this Javascript file to work it needs to export an object.

To create the file, first you have to create a .vuepress folder inside your project, then create an empty file inside it and name it config.js.

To activate the header and search feature we just need to add the title and description into the exported object.

The config options are broken down into 5 sections:

This consists of the least configuration needed to get things up and running, they include:

base: set the base directory of the site

title: set the title of the site

description: set the content of the meta tag named description

<meta name="description" content="">

head: add other tags you would like to add in the head section of the HTML page.

dest: set which folder the compiled files will be outputted when you run vuepress build

ga: specify the ID of your Google Analytics Account

serviceWorker: specify if you want VuePress to automatically generate and register a service worker that would cache the content for offline use

port: specify the port to run the dev server on

Config file showing the basic configuration options

This consists of all configs relating with the theme to be used in the site.

theme: pass the name of a custom theme you would prefer to use

themeConfig: specify all the theme configurations possible for a particular selected theme

This allows you to customize the markdown extension based on your needs, they include:

markdown.slugify: Lets VuePress to convert header texts into slugs

markdown.anchor: processor will render header tags as links

markdown.toc: decides if the processor should render [[toc]] or not

markdown.config: add additional plugins that are not in the VuePress markdown system

This allows you to specify how your production ready file is built. It includes:

postcss: select options for the PostCSS loader

configureWebpack or chainWebpack modify the internal webpack config in VuePress

This provides options that lets the VuePress build to disable some backward compatibility features such as ES5 transpilation, polyfills for IE, etc.

The above can be done with evergreen.

The default theme consists of a homepage which has the following:

  1. Hero image
  2. Action button
  3. A section composed of three columns with each having a title and a caption.
  4. A footer

The default theme has already created some preset variable in the theme’s YAML front matter that allows us to set the actual data that would be used on the site.

To set these values, you need to create a file in the root of your project and specify the correct values in the metadata below;

Markdown file with the various sections of the default homepage filled with data

home either turn off the homepage view or display it

heroImage specify the link of the hero image on the homepage

actionText specify the text on the action button on the homepage

actionLink allows you to specify what link to navigate to when the action button is clicked

Features specifies content into all the 3 columns of the default theme

footer allows you to specify the content of the footer of the page

To enable the navigation links on the header of the page, the default theme provides a themeConfig.nav option in the config.js which allows you set the various navigation links.

Example showing the various navigation supported

To enable the sidebar layout, the default theme provides a themeConfig.sidebar option, that allows us to specify the various links in the sidebar.

The sidebar also has a grouping feature of links which you can specify if you want it collapsible or not.

For a sidebar item to be visible, the file being referenced has to exist.

Example showing sidebar with a section name Main and it’s children links

NOTE: Sidebar only works in markdown files that don’t have the home option set to true.

The default theme stylesheet was built with a preprocessor called stylus which allows us to define variables in stylesheets.

This makes it easy for us to change a few preset colors and the styles get applied across.

To override some of the styles you have to create an override.styl file in the .vuepress folder and specify the value changes.

List of variables you can currently override

Deploying a VuePress site is pretty easy, depending on the platform of your choice.

First, we have to make a production-ready site.

To do this we change the directory of our terminal to the root of our project and then run the code below

vuepress build

This compiles our markdown into vue components which in turn is processed by the VuePress build setup to generate a fully pre-rendered single page application that is both fast and SEO-friendly in the .vuepress/dist directory unless stated otherwise in the config.js file.

Now you can deploy your production ready site, the way you would deploy any other static website.

Found this article helpful? Don’t forget to clap and share :)

LogRocket is a frontend logging tool that lets you replay problems as if they happened in your own browser. Instead of guessing why errors happen, or asking users for screenshots and log dumps, LogRocket lets you replay the session to quickly understand what went wrong. It works perfectly with any app, regardless of framework, and has plugins to log additional context from Redux, Vuex, and @ngrx/store.

In addition to logging Redux actions and state, LogRocket records console logs, JavaScript errors, stacktraces, network requests/responses with headers + bodies, browser metadata, and custom logs. It also instruments the DOM to record the HTML and CSS on the page, recreating pixel-perfect videos of even the most complex single page apps.

Try it for free.

Tag cloud