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.

Why VuePress?

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

  [[toc]]

• 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.

Getting started

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.

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.

module.exports = {
  title: 'Hello VuePress World',
  description: 'Just playing around... Skr Skr!'
}

The config options are broken down into five 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 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

module.exports = {
  dest: 'docs',
  title: 'VuePress',
  description: 'Just playing around.. Skr! Skr!',
  head: [
    ['link', { rel: 'icon', href: `/logo.png` }],
    ['link', { rel: 'manifest', href: '/manifest.json' }],
    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
    ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
    ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
    ['link', { rel: 'apple-touch-icon', href: `/icons/apple-touch-icon-152x152.png` }],
    ['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#3eaf7c' }],
    ['meta', { name: 'msapplication-TileImage', content: '/icons/msapplication-icon-144x144.png' }],
    ['meta', { name: 'msapplication-TileColor', content: '#000000' }]
  ],
  serviceWorker: true,
  ga: 'UA-109510157-1',
  port: 8000
}

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
• configureWebpack or 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:

1. Hero image
2. Action button
3. A section composed of three columns, each with a title and 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 readme.md file in the root of your project and specify the correct values in the metadata below:

---
home: true
heroImage: /hero.png
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
  details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

# Hello VuePress World!

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

Navbar Links

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.

module.exports = {
  themeConfig: {
    nav: [
      // Normal Links
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
      
      // Links with dropdown
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese' },
          { text: 'Japanese', link: '/language/japanese' }
        ]
      },
      
      // Grouped Items inside dropdown
      {
        text: 'Languages',
        items: [
          { 
            text: 'Group1', 
            items: [
              { text: 'Chinese', link: '/language/chinese' },
              { text: 'Japanese', link: '/language/japanese' }
            ] 
          },
        ]
      }
    ]
  }
}

Sidebar layouts

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.

---
home: true
heroImage: /hero.png
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
  details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

# Hello VuePress World!

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

Switching colors

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:

// colors
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc

// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px

// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px

Deploying

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 🙂