Up and Running with VuePress

Learn how to use VuePress, a static site generator, to build a documentation site.

A static site generator takes source files and generates an entire static website. Static site generators require fewer server resources, are scalable, and can handle high volumes of traffic. Today, there are many static site generators available and used for all sorts of purposes. Some are used solely for documentation sites, for a website with a blog, or for both documentation websites and blogs. I’ve used Gitbook for documentation sites in the past, and I decided to try VuePress.

VuePress is a static site generator built on Vue.js. It was built to support the documentation needs for Vue.js related projects. VuePress makes it easy to add documentation to existing projects, and content can be written in Markdown. The default theme it uses is optimized for technical documentation sites. I’ll show you how to get started with VuePress by building a minimal technical documentation site.

Project Setup

VuePress requires Node.js version 8 or higher. Also, you’ll need Vue CLI installed to follow along (I’m using Vue CLI 3). Open the command line and follow the instructions below to set up the project.

1. Run vue create vuepress-doc. This should ask you to select a preset. Select default and press Enter.
2. Run cd vuepress-doc to change directory to the directory of the Vue project.
3. Add VuePress dependency to the project by running the command npm install -D vuepress.
4. Run mkdir docs to create a new directory named docs. This will contain files for the VuePress docs.
5. Switch to the docs directory (cd docs), and create a new directory by running mkdir .vuepress.

The above instructions should leave you with a Vue project that will power the documentation website we will build using VuePress. The docs folder will contain files for the website, and the .vuepress folder will specifically contain files to set VuePress configuration, components, styles, etc. Open package.json and add the following scripts:

"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"

The command vuepress dev docs will start the local development server for VuePress, with docs as the name of the directory to pick content from. The vuepress build command will generate static assets which can be deployed to any hosting environment.

Adding The Home Page

Now that the project is set up, we’ll need to add a home page, which will be displayed by the / route. Add a new file .vuepress/config.js with the content below.

module.exports = {
  title: "VuePress",
  description: "My VuePress powered docs"
};

This file is essential for configuring VuePress. The title property will be set as the title for the site. This will be the prefix for all page titles, and it will be displayed in the navbar in the default theme. The description is the description for the site. This will be rendered as a tag in the page HTML.

In the docs folder, add a new file README.md. Open it and add the content below to it.

---
home: true
heroImage: https://vuepress.vuejs.org/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: Copyright © 2019 - Peter Mbanugo
---

### As Easy as 1, 2, 3

```bash
# install
yarn global add vuepress
# OR npm install -g vuepress

# create a markdown file
echo '# Hello VuePress' > README.md

# start writing
vuepress dev

# build to static files
vuepress build
```

We’re using the default theme that comes with VuePress. It provides a default home page layout, which we can customize by specifying some predefined variables in the YAML front matter of the file. Setting the home variable to true tells it to style the page using the default home page style. What this default style renders is a hero image with text and a features section. The text is gotten from the title and description you set in .vuepress/config.js. Anything after the YAML front matter will be parsed as normal Markdown and rendered after the features section. Let’s see how what we have so far looks like in the browser. Open the command line and run npm run docs:dev. This should start the local dev server and you can access the website at localhost:8080 by default.

What this gives us is a nice-looking home page with a navbar. The navbar by default has the website’s title and a search box.

Adding A Navbar

Let’s add a navbar that allows navigating to other sections of the website. We will do this by setting themeConfig property in .vuepress/config.js. Open that file and add the following properties to the exported object.

themeConfig: {
  nav: [
    { text: "Guide", link: "/guide/" },
    { text: "Author", link: "https://pmbanugo.me" }
  ];
}

This gives us two links on the navbar. If you click the Guide link, it’ll redirect to a 404 page. That’s because there is no file to resolve this route. The default route setting will resolve / to README.md on the root directory, /guide/ will resolve to /guide/README.md, and /guide/setup.html will resolve to /guide/setup.md.

Go ahead and create a new folder guide and a file README.md with the following content.

# Introduction

VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system, and a default theme optimized for writing technical documentation. It was created to support the documentation needs of Vue's own sub-projects.

Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, however, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site.

## How It Works

A VuePress site is in fact a SPA powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). 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. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/).

Each Markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/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.

## Features

- [Built-in Markdown extensions](./markdown.md) optimized for technical documentation
- [Ability to leverage Vue inside Markdown files](./using-vue.md)
- [Vue-powered custom theme system](./custom-themes.md)
- [Automatic Service Worker generation](../config/README.md#serviceworker)
- [Google Analytics Integration](../config/README.md#ga)
- ["Last Updated" based on Git](../default-theme-config/README.md#last-updated)
- [Multi-language support](./i18n.md)
- A default theme with:
  - Responsive layout
  - [Optional Homepage](../default-theme-config/README.md#homepage)
  - [Simple out-of-the-box header-based search](../default-theme-config/README.md#built-in-search)
  - [Algolia Search](../default-theme-config/README.md#algolia-search)
  - Customizable [navbar](../default-theme-config/README.md#navbar) and [sidebar](../default-theme-config/README.md#sidebar)
  - [Auto-generated GitHub link and page edit links](../default-theme-config/README.md#git-repo-and-edit-links)

## To-Do

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

- Plugin support
- Blogging support

Contributions are welcome!

## Why 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.

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

### GitBook

We've been using GitBook for most of our sub-project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue-based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.

Now when the Guide link is clicked, it redirects to the proper page. There are more things you can do on the navbar, but for the sake of brevity, we’re going to have just those two links in the navbar. Check the docs to learn more on how to disable navbar for a particular page or how to add dropdown menu.

Adding A Sidebar

VuePress also provides an easy way to configure sidebar navigation. In the most basic form, you can set the themeConfig.sidebar property to an array of links to display on the sidebar. We’re going to use the most basic form for this walkthrough application, but if you want to learn about the other ways to set up the sidebar, the docs is your best resource.

Add a new file getting-started.md to the guide directory. Open it and add the content in it.

# Getting Started

::: warning COMPATIBILITY NOTE
VuePress requires Node.js >= 8.
:::

## Global Installation

If you just want to play around with VuePress, you can install it globally:

```bash
# install globally
yarn global add vuepress # OR npm install -g vuepress

# create a markdown file
echo '# Hello VuePress' > README.md

# start writing
vuepress dev

# build
vuepress build
```

## 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. This setup also allows you to use CI or services like Netlify for automatic deployment on push.

```bash
# install as a local dependency
yarn add -D vuepress # OR npm install -D vuepress

# create a docs directory
mkdir docs
# create a markdown file
echo '# Hello VuePress' > docs/README.md
```

::: warning
It is currently recommended to use [Yarn](https://yarnpkg.com/en/) 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.
:::

Then, add some scripts to `package.json`:

```json
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
```

You can now start writing with:

```bash
yarn docs:dev # OR npm run docs:dev
```

To generate static assets, run:

```bash
yarn docs:build # Or npm run docs:build
```

By default the built files will be in `.vuepress/dist`, which can be configured via the `dest` field in `.vuepress/config.js`. The built files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services.

Add sidebar: ["/guide/", "/guide/getting-started"] to the themeConfig property in config.js. When you save this file, the app should reload in the browser, now displaying a sidebar for the /guide route.

The text for the sidebar links are automatically inferred from the first header in the page. You can optionally set this in the title property of the YAML front matter for the page, or use an Array in form of [link, text].

Searching The Docs

VuePress has a built-in search functionality which builds its index from the h1, h2 and h3 headers.

You can disable the search box with themeConfig.search: false, or customize how many suggestions will be shown with themeConfig.searchMaxSuggestions. You can extend this to use full-text search with Algolia. See the docs for info on setting this up.

That’s A Wrap 🚀

VuePress makes it easy to build a technical documentation site. Through the course of this blog, we’ve built a simple documentation site that has search functionality, a navbar, and sidebar. There are a lot more options that can be configured (e.g Service Worker and custom layout page). To learn more, visit vuepress.vuejs.org.

---

For More Info on Building Great Web Apps

Want to learn more about creating great user interfaces? Check out Kendo UI  - our complete UI component library that allows you to quickly build high-quality, responsive apps. It includes all the components you’ll need, from grids and charts to schedulers and dials, and includes a library built just for Vue.