VuePress is a Vue-powered static site generator that is composed of two parts:
- A theming system
- 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:
1. Vue inside Markdown files
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.
2. Built-in Markdown extensions
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.
3. Default theme
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.
4. Custom theme
VuePress makes it easy to customize the default theme as well as create a completely custom theme.
5. Service workers
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.
6. Google Analytics
VuePress also comes with integrated Google Analytics. To enable it, you have to add your Google Analytics ID in the config.
7. Multilanguage support
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:
- Installing it globally
- 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.
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.
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
To activate the header and search feature we just need to add the
description into the exported object.
The config options are broken down into 5 sections:
1. Basic config
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
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
2. Theming config
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
3. Markdown config
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
4. Build config
This allows you to specify how your production ready file is built. It includes:
postcss: select options for the PostCSS loader
chainWebpack modify the internal webpack config in VuePress
5. Browser Compatibility config
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.
Coupling the default theme parts together
The default theme consists of a homepage which has the following:
- Hero image
- Action button
- A section composed of three columns with each having a title and a caption.
- 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
readme.md file in the root of your project and specify the correct values in the metadata below;
Explaining the code above
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.
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.
NOTE: Sidebar only works in markdown files that don’t have the
home option set to
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
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
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 🙂
Plug: LogRocket, a DVR for web apps
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.
Try it for free.