VuePress: What is it and Why it is a great tool to use

VuePress Vue-powered Static Site Generator

VuePress has been officially out for some time now and some people may wonder why it's so great or why bothering using it, I don't write docs that often some may say. Well, you may never use it but before you forget all about it, read what can you do with it and how.

VuePress is a Minimalistic Vue-powered static site generator with Vue component based layout and is the latest project from Vue creator Evan You. On the client side, a VuePress site is an SPA powered by Vue, Vue Router, and Webpack. It was originally created to support the documentation needs of Vue’s own subprojects and now it can serve your own needs.

How It Works

As stated in the guide it is composed of two parts:

  1. A minimalistic static site generator with a Vue-powered theming system
  2. A default theme optimized for writing technical documentation

Things you can do with it:

  • Write Vue inside Markdown files
  • Create a custom theme from the default one or create one from scratch
  • Add your own language (more below)
  • Benefit for the Vuepress setup which already has hot reload enabled

A VuePress site is, in fact, an SPA powered by Vue. If you’ve used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!). During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. Each markdown file is compiled into HTML with markdown-it and then processed as the template of a Vue component. This allows you to directly use Vue inside your markdown files and is great when you need to embed dynamic content.

Why use Vuepress and not Nuxt?

Nuxt is capable of doing what VuePress does, but it is designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box. inspired by Nuxt's nuxt generate command and other projects like Gatsby.

Docsify / Docute

Both are great projects and also Vue-powered. Except they are both completely runtime-driven and therefore not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices.

Hexo

Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure.

Features

Todo Features

Note: Vuepress is still a work in progress.. There are a few things that it currently does not support but is planned:

  • Blogging support
  • Algolia DocSearch Integration

In Action

Installing and using Vuepress is fairly easy. Install VuePress

yarn global add vuepress # OR npm install -g vuepress

Note here that VuePress requires Node.js >= 8.

Create a markdown file

echo '# Hello VuePress' > README.md

Start by adding some text to the file

Then run:

vuepress dev

for later usage - build to static files

vuepress build

In windows OS you might end up with some problems while using the echo '# Hello VuePress' > README.md command. Also, remember the note that says:

WARNING: It is currently recommended to use Yarn instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency. Npm fails to generate the correct dependency tree in this case.

Inside an Existing Project

If you have an existing project and would like to keep documentation inside the project, you should install VuePress as a local dependency.

Working, sweet.

Writing your own stuff

If you want to build someting other than a simple docs page, you have to enable some of the features of Vuepress (homepage, sidebar, navigation etc), meaning you need to create fisrt a config file.

Go ahead and create the following directory/file .vuepress/config.js in your project. It should export a JavaScript object:

module.exports = {
  title: 'Getting to Know VuePress',
  description: 'Horsing around'
}

The above enables you to change the title and description of your page.

Here you can add any configuration option you like, available at the config reference page. With this file, you have the power use all the cool stuff.

Internationalization

Let's see an example of how to leverage multi-language support in VuePress. You first need to use the following file structure:

/docs
├─ .vuepress
├─ README.md
├─ /nested/
│  └─ foo.md
└─ /el/
   ├─ README.md
   └─ /el/nested/
      └─ bar.md

Here I am going to use Greek as a second language. Specify the locales option in the config.js:

...
locales: {
    // The key is the path for the locale to be nested under.
    // As a special case, the default locale can use '/' as its path.
    '/': {
        lang: 'en-US', // this will be set as the lang attribute on <html>
        title: 'VuePress',
        description: 'Vue-powered Static Site Generator'
    },
    '/el/': {
        lang: 'el-GR',
        title: 'VuePress - Greek',
        description: 'Vue ΓΕΝΝΗΤΡΙΑ ΣΤΑΤΙΚΩΝ ΣΕΛΙΔΩΝ'
    }
}
...

So now I am able to write some words in the chosen language and maybe use an image to create a healthy appetite for junk food to my users. So adding images to Vuepress, same as markdown, easy, neat.

In my README.md file:

### I can even write some stuff in Greek

`Fae ena souvlaki` meaning *eat a souvlaki*

// image
![souvlaki](SOMEURL)

And there you have it: Locale vuepress

Wise words from the guide: All markdown files are compiled into Vue components and processed by webpack, therefore you can and should prefer referencing any asset using relative URLs. This would work the same way as in .vue file templates. The image will be processed with url-loader and file-loader, and copied to appropriate locations in the generated static build.