How To Build a Documentation System with Vue and VuePress

Introduction

Documentation is a critical part of a successful project. However, your project may not require a full-fledged documentation system. In these situations, static pages will likely suffice.

VuePress parses Markdown files structured in folders into HTML files to be served. VuePress ships with Vue, Vue Router, and webpack. Each Markdown file is parsed as a Vue template and assets are bundled by webpack. Parsing the Markdown files into Vue templates allows you to also utilize native Vue scripts in the form of single-file components.

In this article, you will build out a static documentation website which is also a single page application using the Vue-powered static site builder, VuePress.

Prerequisites

If you would like to follow along with this article, you will need:

• A local development environment for Node.js. Follow How to Install Node.js and Create a Local Development Environment.

This tutorial was verified with Node v16.6.2, npm v8.1.0, and vuepress v1.8.2.

Step 1 — Setting Up the Project

In this section, you will create your project and install VuePress.

First, create a new project directory:

mkdir vuepress-example

Next, change into the new project directory:

cd vuepress-example

Then, initialize a new project:

npm init --yes

This command quickly scaffolds a new project and creates a package.json file.

Next, install VuePress locally as a dev dependency with:

npm install vuepress@1.8.2 --save-dev

Once VuePress is installed in the project, you will have everything you need because VuePress ships with the default documentation theme used for this project.

At this point, you should modify your package.json for scripts to build and serve the VuePress site.

Open package.json in your code editor and add the highlighted lines of code:

{
  "name": "vuepress-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^1.8.2"
  }
}

At this point, you have installed VuePress and modified your package.json to support the dev and build commands.

Step 2 — Creating the Home Page

In this section, you will create the directory structure and Markdown files with placeholder text.

Take care when creating folders in VuePress, because it evaluates the folders and Markdown files according to their directory structure. Each Markdown file in a folder compiles into an HTML document with the route being the parent folder.

First, create a docs directory to house the components and configuration:

mkdir docs

Now, use your code editor to create a new index.md file in this directory:

---
home: true
actionText: Counter Component
actionLink: /counter/
features:
- title: Embedded Vue Compments
  details: A Vue counter developed using Vue is embedded in this documentation. Now that's the power of VuePress!
- title: Documentation made with VuePress
  details: This entire documentation was made with VuePress which parsed Markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---

Special “front matter” syntax (either in YAML, JSON, or TOML format) in the Markdown files instruct VuePress to provide title, lang, and other attributes.

At this point, you can build and serve the application and observe what you have so far:

npm run docs:dev

After the application is built, you will be presented with a success message that also provides the URL to visit (by default it should be localhost:8080).

Now, open this URL in your web browser. The Markdown code will generate a button for Counter Component, informational columns about features, and a footer.

VuePress ships with a hot reload feature that implements any change made to the application during development.

However, a restart of the development server is required if the Vue components are created while the local development server is live.

Step 3 — Creating the Counter Page

For the purposes of this project, your documentation will track the details of a Counter component that increments and decrements a numeric value.

Under the docs directory, create a new .vuepress subdirectory:

mkdir docs/.vuepress

And under this .vuepress directory, create a new components subdirectory;

mkdir docs/.vuepress/components

Now, use your code editor to create a new counter.vue file in the .vuepress/components directory:

<template>
  <div class="counter">
    <h1>{{ number }}</h1>
    <button @click="increment">Increment</button>
    <button @click="decrement">Decrement</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      number: 0
    };
  },
  methods: {
    increment() {
      if (this.number >= 0) {
        this.number++;
      }
    },
    decrement() {
      if (this.number > 0) {
        this.number--;
      }
    }
  }
};
</script>

<style scoped>
.counter {
  display: inline-block;
  margin-left: 30%;
}

button {
  display: inline-block;
  padding: 20px;
  margin: 10px;
  font-weight: bold;
  border-radius: 5px;
  box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
}

h1 {
  text-align: center;
}
</style>

This code will display the value (number) and depending on how many times Increment or Decrement buttons are interacted with, that value will change.

Now, you will create the page to display the <counter/> component.

Under the docs directory, create a new counter subdirectory:

mkdir counter

Now, use your code editor to create a new README.md file in the docs/counter directory:

---
title: Counter Component
---
# Counter Component

<counter/>

## Details

The `counter` component allows users to **Increment** and **Decrement** numeric values. The value starts at `0` and has a minimum value of `0`.

### Props

n/a

### State

n/a

Create a couple of additional pages in this directory. This demonstration will include usage.md:

---
title: Counter Component - Usage
---
# Usage

Currently, this component is used in our app as part of a demonstration.

And see-also.md:

---
title: Counter Component - See Also
---
# See Also

* [Number](https://en.wikipedia.org/wiki/Number)
* [Increment and decrement operators](https://en.wikipedia.org/wiki/Increment_and_decrement_operators)

These files will later be transformed into static pages.

Now you have all the required Markdown files.

Step 4 — Configuring the Layout and Styles

In this section, you will configure the site to use a specified title, description, nav, and sidebar.

The config.js file is used to customize the documentation system. Use your code editor to create a new counter.vue file in the .vuepress directory:

module.exports = {
  title: 'VuePress',
  description: 'A demo documentation using VuePress',
  themeConfig: {
    nav: [
      { text: 'Counter', link: '/counter/' }
    ],
    sidebar: [
      {
        title: 'Counter',
        collapsable: false,
        children: [
          ['/counter/usage', 'Usage'],
          ['/counter/see-also', 'See Also']
        ]
      }
    ]
  }
};

First, you specify the title of the website and assign it a description, which is good for SEO. This title and description automatically provide an indexed search system on the website with a search bar.

Next in the script is the themeConfig object, which receives parameters required to implement certain functionality on the theme. To create a navbar, you create a nav array that contains objects specifying the display text and route of each nav element.

This code also features grouped sidebars so users can have a quick glance at the menu at any time in the documentation. The sidebar menu can be set to collapse by default using the collapsable property on the sidebar group.

As a final step to configuring the demonstration, you will override the default colors using styles.

Under the docs/.vuepress/ directory structure, create a new styles subdirectory:

mkdir docs/.vuepress/styles

Now, use your code editor to create a new palette.styl file in the .vuepress/styles directory:

$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

This syntax and file extension is for Stylus sheets. VuePress uses Stylus for configuring colors and breakpoints.

Save your changes and restart the development server with the following command:

npm run docs:dev

Note that changes made to the .styl file are reflected in the browser immediately.

You have now completed the documentation system with individual pages.

Conclusion

In this tutorial you developed a static documentation website, which is also a single-page app, using VuePress.

VuePress offers the flexibility of writing Vue scripts inside Markdown files which introduces interactive demonstrations. Static sites are considered useful for their speed, security, and maintainability.

VuePress is SEO-friendly and by default provides a means to implement analytics tracking using Google Analytics on your pages. Also, VuePress ships with a minimal search system that indexes all headers on the website and displays them upon search. Although VuePress ships with a default responsive layout for documentation, it also supports custom layouts for styling.

Continue your learning by modifying the project to include additional folders and corresponding Markdown files.

If you would like to learn more about the options available to VuePress, consult our introduction to VuePress.