An Introduction to VuePress

You may have heard of VuePress recently, it appeared almost overnight and shortly thereafter became Product of the Day on ProductHunt. What is it about VuePress that makes it so special? What is VuePress? Well, it’s effectively a static site generator. Particularly, a Vue.js-powered static site generator aimed toward building documentation websites. Why’s that so special? The creator, Evan You, has a knack for building incredibly simple but flexible software. After all, he made Vue.js. VuePress is no different. After running two commands, you’ll have a zero-configuration prerendered, SEO-friendly SPA with full Vue.js support. A few lines of config and it will be personalized to fit your needs.

Getting Started

Step 1: Install VuePress.

$ npm install -g vuepress

Step 2: Write something.

Create README.md in a folder and write some markdown (mixed with Vue.js expressions!) in it.

## Hello VuePress!

_How are you doing?_
> **I'm doing fine, thanks!**

_Great, I was wondering what `49 + 32` is?_
> **{{49 + 32}}**

_Could you repeat that a few times?_

> **Sigh...**
<p v-for="i of 3">{{49 + 32}}</p>

Run $ vuepress dev in that folder and visit the resulting URL. (It has hot module reloading!)

The result should look something like this:

As you can see, if you’re familiar with Vue’s templating system at all, you’ll feel right at home with VuePress. Also, if you’re paying attention, you’ll see that headers in the page become anchors that you can link to, which comes in handy.

Step 3: Build It.

When you’re ready to publish your site, run $ vuepress build. The resulting output will be in .vuepress/dist, nicely built and minified with Webpack.

But you’ll probably want to make a few tweaks first, won’t you? A single page is a bit boring.

Post Metadata

First things first, go ahead and create a couple more markdown files in your project directory.

# This is Page 1

Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

# This is Page 2

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.

If you check your browser now, you’ll notice that some magical next / previous post links have appeared. The text of those links will be the same as the first header in those posts. In this case, that means This is Page 1/2. That’s not quite what we want.

Go ahead and add a YAML Front-matter block at the top of the two page markdown files.

---
title: Page 1
# We can even add meta tags to the page! This sets the keywords meta tag.
# <meta name="keywords" content="my SEO keywords"/>
meta:
  - name: keywords
  - content: my SEO keywords
---

# This is Page 1

...

---
title: Page 2
---

# This is Page 2

...

With that, your links should now say Page 1 and Page 2 instead of This is Page ....

Here’s the full list of front-matter metadata.

Adding a Sidebar

Navigating with forward / next links is kind of inconvenient, isn’t it? Also, the pages seem kind of out-of-order. Wouldn’t it be nice if there was a sidebar or something that could solve both of those problems?

VuePress’ default theme comes with support for a powerful sidebar, but to enable it, you’ll need to create a simple configuration file.

Go ahead and create .vuepress/config.js in your project directory and enable the sidebar.

module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/Page 1',
      '/Page 2'
    ]
  }
}

That’s all you need for a basic sidebar, but there are a variety of other configuration options as well.

Enabling the Navbar

So you’ve got pages and sidebars, but the site still feels a little bland. Why not spruce things up by adding a navbar and search functionality?

module.exports = {
  title: 'My VuePress Site',

  themeConfig: {
    sidebar: [
      ...
    ],

  }
}

Turns out all you need to do to create the navbar and search field is add a title to your site! Talk about convenient! And the search functionality works out-of-the-box!

(There are a few other things you can do to configure the navbar, of course.)

Using Vue Components

Let’s kick things up a notch. The true power of VuePress lies in its ability to use Vue components in pages.

Let’s create a Vue component that lets us increment and decrement a number. (Really important stuff here, folks.) VuePress automatically detects Vue components created in .vuepress/components, so let’s go ahead and create .vuepress/components/NumberModifier.vue

<template>
  <div class="number-modifier">
    <button @click="increment()">+</button>
    <strong> {{value}} </strong>
    <button @click="decrement()">-</button>
  </div>
</template>

<script>
export default {
  props: ['start'],

  // We have to copy the value because we can't use v-model with
  // nothing to bind to.
  // (VuePress doesn't have support for reactive page variables at the moment.)
  data() {
    return {
      value: this.start
    }
  },

  methods: {
    increment() { this.value++ },
    decrement() { this.value-- }
  }
}
</script>

And just like that, we can use it in any post. For example, Page-1.md

...
# This is Page 1

**Our Component:**
<NumberModifier :start="5"></NumberModifier>

Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

The same method applies to any component. This makes it an excellent way to demonstrate the components you write inline with your documentation for them, or even build more advanced sites! It’s all up to you.

Custom Themes

Not everyone wants their static site to look just like every other one built with the same tools, so most likely you’ll eventually want to start customizing things.

Basic modifications

The default theme uses Stylus as its CSS preprocessor. If all you want to do is change a color or two, you can accomplish that by adding .vuepress/override.styl and modifying a few values in it. You could even add a few CSS overrides in there if needed.

The default theme is basic enough that all you’ll probably want to change is the accent color.

// Color configuration
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

// Layout configuration
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px

Creating a new theme

In VuePress, themes are just collections of Vue components and related assets. If you want to get started with your own theme, the easiest way is to eject the default theme using $ vuepress eject. All this does is copy the default theme files to .vuepress/theme.

If you take a look at the default theme, you’ll discover that it’s incredibly easy to understand. Fewer than 25 files with an average of ~70 lines apiece. Basically no boilerplate.

You can go ahead and start customizing the theme right off the bat. Components will be hot-reloaded just like the rest of your site! For more details on custom themes, take a look at the docs.

Conclusion

VuePress is just getting started, and I can already say it looks awesome. Even if you’re not planning on building anything with it right away, keep an eye on the offical docs. Things are only going to get better from here.