How To Build a Documentation System with Vue and VuePress

Updated on November 22, 2021

William Imoh

How To Build a Documentation System with Vue and VuePress


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.

Note: This tutorial was written with manual installation in mind. An automated scaffolding tool called create-vuepress-site is also available.

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.


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

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:

  1. mkdir vuepress-example

Next, change into the new project directory:

  1. cd vuepress-example

Then, initialize a new project:

  1. 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:

  1. 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:

  1. mkdir docs

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

home: true
actionText: Counter Component
actionLink: /counter/
- 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:

  1. 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:

  1. 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:

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

export default {
  data() {
    return {
      number: 0
  methods: {
    increment() {
      if (this.number >= 0) {
    decrement() {
      if (this.number > 0) {

<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;

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:

  1. mkdir counter

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

title: Counter Component
# Counter Component


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


### State


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.

Note: You can learn more about the navbar in the official documentation.

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.

Note: You can learn more about the sidebar in the official documentation.

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:

  1. 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:

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


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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors
Default avatar
William Imoh


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

The command “vuepress dev docs” fails with the error message “‘vuepress’ is not recognized as an internal or external command”. I am executing this command in the ‘vuepress’ folder, as the tutorial requests. vuepress module exists in the node_modules folder (a consequence of the ‘npm install -D vuepress’ step executed earlier in this tutorial)

I am using npm 6.14.7

Why is the vuepress not accessible?

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel