VuePress vs Nuxt.js

Derick Sozo
Apr 23, 2018 · 5 min read

Evan You, the creator of Vue, recently made a splash with the release of VuePress, a new Vue-powered static site generator.

A static site is one that’s written in plain HTML and that HTML is served as-is to the user. A static site generator takes source files (Markdown, Vue files, or anything else) and dynamically generates an entirely static HTML website. This can help drastically improve your SEO.

If you’re familiar with Nuxt.js you might already know that it has a feature called nuxt generate that allows you to create a static version of your application by generating every route as an HTML file.

You might be asking, “How is VuePress different from Nuxt? What can I do with VuePress that I can’t do with Nuxt? Can I use VuePress to create a blog?”

In this post, we’ll go over the biggest differences between the two and the main benefits for using VuePress.

Apps vs Documentation

Nuxt, first and foremost, is a higher-level framework whose purpose is to simplify the development of universal JavaScript applications. It has a feature called nuxt generate that allows you to create a static version of your application by generating every route as an HTML file.

VuePress, on the other hand, is a static site generator that makes the creation of documentation websites easier, such as the Vue.js docs. VuePress was inspired by Nuxt’s nuxt generate feature along with other similar frameworks like Gatsby.js, a static site generator for React.

Everything that you can do with VuePress you can also do with Nuxt. You can think of VuePress as a subset of what Nuxt is capable of with features that make it easy to handle the creation of a lot of content.

Here are 3 ways VuePress makes it easy for you to write content-heavy documentation out of the box.

1. Use Markdown for Content

With VuePress you get native compilation of your markdown files by default. In other words, you can write a markdown file and then have it converted into HTML without any extra setup of conversion plugins.

Nuxt doesn’t compile markdown files by default so there’s more setup involved in getting markdown compilation to work.

For example, Nuxt uses Nuxt itself for their own documentation. They also use markdown for their content, but they had to implement an intermediary API server to translate their markdown files into JSON for the site to consume. All of these intermediate steps can be avoided with VuePress.

Use Vue Components inside your markdown

Another added benefit of VuePress is that it powers up your markdown by allowing you to use Vue components directly in the markdown file. The way this works is that each markdown file is first compiled into HTML and then passed on as a Vue component to vue-loader. This means you can use Vue templates and components in your text.

# Blogging Like a Hacker**My Component:**<Stats :start="3"></Stats>
<p v-for="n of 15">{{ n }}</p>

YAML Front-matter in your markdown files

You can also put YAML, a data serialization language commonly used for configuration, front-matter at the top of your markdown files and VuePress will automatically interpret it for you.

---
title: Blogging Like a Hacker
lang: en-US
---# Blogging Like a Hacker**My Component:**

You can use YAML front-matter to set up your titles, meta description, and other SEO-related tags on your individual pages.

Click here to learn more about everything else that you can do with Markdown in VuePress, checkout the markdown section in their documentation.

2. Multi-language support out of the box

VuePress is also set up with i18n support by default so that your documentation site can support a variety of different languages. For example, the VuePress site itself is set up with a version in Chinese.

You can add extra language locales by adding a locales object into the themeConfig object in your config.js file for your VuePress project.

locales: {
  '/': {
    label: 'English',
    selectText: 'Languages',
    editLinkText: 'Edit this page on GitHub',
    nav: [
      {
        text: 'Guide',
        link: '/guide/',
      },
      {
        text: 'Config Reference',
        link: '/config/'
      },
      {
        text: 'Default Theme Config',
        link: '/default-theme-config/'
      }
    ],
    sidebar: {
      '/guide/': genSidebarConfig('Guide')
    }
  },
  '/zh/': {
    label: '简体中文',
    selectText: '选择语言',
    editLinkText: '在 GitHub 上编辑此页',
    nav: [
      {
        text: '指南',
        link: '/zh/guide/',
      },
      {
        text: '配置',
        link: '/zh/config/'
      },
      {
        text: '默认主题',
        link: '/zh/default-theme-config/'
      }
    ],
    sidebar: {
      '/zh/guide/': genSidebarConfig('指南')
    }
  }
}

To see the full example, checkout the config.js file for the VuePress documentation website up on GitHub here.

3. Fully-featured Default Theme

VuePress comes with a default theme designed for smoothly going through technical documentation. It gives you a sidebar where all your pages are listed and a navbar with a fully-featured site-wide search as well.

Click here to see the different options that you can customize with the default VuePress theme.

Can I create a blog with VuePress?

Yes, technically you could, but as of right now (April 2018) it doesn’t have all of the features that other static blogging frameworks, like Jekyll for example, have. For starters, it’s missing a tagging system and a more blogger-friendly default template.

Making VuePress more blog-friendly is on the roadmap. Blog support is actively being discussed, and according to Evan You the main goal is getting VuePress core’s API to a point where the community can go in and start adding features for blogging support.

If you’re interested in keeping up with the progress on making VuePress blog-friendly checkout this GitHub issue where it’s being actively discussed.

So when should I use VuePress?

The best time to use VuePress is if you’re creating a documentation website that is using Markdown for content. If you’re already using Nuxt for something similar, it’s seriously worth considering VuePress for a switch.

Is there anything you would like to know about VuePress? Or if you have any extra questions about it leave it as a comment below and I’ll get back to you asap.

Keep Reading

Vue Mastery

The ultimate learning resource for Vue.js Developers

Derick Sozo

Written by

Learn how to land your next remote project, free: https://remotefreelancers.com/

Vue Mastery

The ultimate learning resource for Vue.js Developers