Building Documentations with Vue Using Vuepress

In this tutorial, learn how you can build your documentation with VuePress, which offers a flexible, configurable and easy to deploy option for creating static sites.

As a developer, trustworthy documentation is a must. Presenting a clear guide of the different aspects of an application helps make information accessible not just to consumers of your application but also to yourself as the need arises. Therefore, having access to a system that eases the process of creating robust and reliable documentation is a plus, and this is where VuePress comes into play.

VuePress is a static site generator that is comprised of two parts: a minimalistic static site generator with a powerful theming system and plugin API, alongside a default theme for generating documentation in no time. VuePress is powered by Vue, Vue Router and webpack. It generates single-page applications that offer great performance, have pre-rendered HTML and are SEO-friendly.

In this post, we’ll walk through how to create documentations with Vue using VuePress. Before we get started, make sure you have Node and NPM installed on your PC. To ensure you have them installed, run the following command on a terminal:

    node -v && npm -v

Note: VuePress requires Node.js version >= 8.

If these commands don’t exist, visit the official Node website to download and install it on your PC.

Once you’re sure that Node and NPM are available on your PC, run the following command to install VuePress globally:

    npm i -g vuepress@next
        OR
    yarn global add vuepress@next

To use the lastest VuePress features like Plugins and Themes, we’ll need to install the version 1.0 alpha.

We’ll be writing markdown, which VuePress compiles into HTML using a library called markdown-it. To get started, create a folder called vue-docs and enter the folder:

    $ mkdir vue-docs && cd $_

Creating Project Files

VuePress analyzes and parses folders and files according to their structure. VuePress has a strict folder-naming convention and it needs to be followed for VuePress to successfully parse and compile the folders and files.

Typically, the VuePress folder structure looks like this:

    vue-docs/
      docs/
        .vuepress/
          styles/
          config.js
        README.md
        guide/
          README.md

Inside the .vuepress directory is where we can further customize the default VuePress theme, create global configuration and create custom components. The .vuepress/styles folder contains global style files. Here we can override the default vuepress colors.

The config.js file is the entry file for configuration and the README.md is the index file and will route to the / path. The guide folder would route to /guide/, and any files within it will have the /guide/ prefix.

Inside the vue-docs directory, run npm init -y to create a package.json file and scaffold a new project. Next, install vuepress locally by running the following command:

    npm i vuepress@next

With VuePress installed, we’re set to go, as VuePress provides a default documentation theme. But in order to personalize the application, we’ll need to configure it further since the default theme doesn’t come with enough content.

Within the vue-docs directory, create a folder named docs and cd into the folder. This folder houses all the project configurations and content.

    mkdir docs && cd $_

Create a .vuepress folder within the docs directory, place cd into the folder and create a file called config.js:

    mkdir .vuepress && cd $_ && touch config.js

The config.js file will hold the general configuration of the application. Within the file, we can describe the application, give it a title and further configure the interface of the application, providing navigation links and choosing how to display the navigation bar. You can read more on the configuration options here.

Open the config.js file and copy the code below into it.

module.exports = {
  title: 'Vue Docs',
  description: 'Building documentations with Vue using VuePress',
  themeConfig: {
    nav: [
      { text: 'Getting Started', link: '/getting-started/' },
      { text: 'API', link: '/api/' },
    ],
  },
};

In the config file, we provided a title for the application as well as the descriptions. In the themeConfig object, we tell VuePress the structure for the navigation. On the header, two anchor elements will be displayed, routing to /getting-started and /api. Before we create content for those routes, we’ll create the index page.

Creating the Index Page

The README.md file located in the root of the docs directory is parsed and compiled as the index page. Using front-matter, we can declare the page as home and VuePress will provide a landing page view with a CTA (call to action) button.

Create a README.md file within the docs folder, open it using an editor and update it with the code below:

    ---
    home: true
    actionText: Get Started
    actionLink: /getting-started/
    ---
    ## Great documentation
    We can create robust and reliable documentations using VuePress

    ## Robust services
    Satisfied conveying an dependent contented he gentleman agreeable do be. Warrant private blushes removed an in equally totally if. Delivered dejection necessary objection do mr prevailed. Mr feeling do chiefly cordial in do. Water timed folly right aware if oh truth. Imprudence attachment him his for sympathize. Large above be to means. Dashwood do provided stronger is. But discretion frequently sir the she instrument unaffected admiration everything.

To boot up a dev server after configuring and creating an index page, run the following command within the vue-doc/ folder:

    vuepress dev docs

This will start up a server on http://localhost:8080. Your view should be similar to the screenshot below:

Creating Routes

In the config file, we included anchor links to two non-existent routes, /getting-started and /api. To create these routes, we need to create two folders within the docs folder that match the naming of these routes. First, we’ll create the /getting-started route. To do this, create a folder named getting-started within the docs folder:

    mkdir getting-started && cd $_

Within the newly created getting-started folder, create a file README.md, which will serve as the index view of the route. Open the file and update it with the code below:

    ---
    title: Vue-docs| Getting started
    description: Getting started with documentations using VuePress
    ---
    # Getting started

    !\[Hero\](https://images.unsplash.com/photo-1513985768785-f12f38ce03cb?ixlib=rb-0.3.5&ixid=eyJhcHBfaWQiOjEyMDd9&s=1eb9fd6388ea9c35e1c7731a8d9e0bdf&auto=format&fit=crop&w=750&q=80)

    Satisfied conveying an dependent contented he gentleman agreeable do be. Warrant private blushes removed an in equally totally if. Delivered dejection necessary objection do mr prevailed. Mr feeling do chiefly cordial in do. Water timed folly right aware if oh truth. Imprudence attachment him his for sympathize. Large above be to means. Dashwood do provided stronger is. But discretion frequently sir the she instrument unaffected admiration everything.

    Tiled say decay spoil now walls meant house. My mr interest thoughts screened of outweigh removing. Evening society musical besides inhabit ye my. Lose hill well up will he over on. Increasing sufficient everything men him admiration unpleasing sex. Around really his use uneasy longer him man. His our pulled nature elinor talked now for excuse result. Admitted add peculiar get joy doubtful.

    Comfort reached gay perhaps chamber his six detract besides add. Moonlight newspaper up he it enjoyment agreeable depending. Timed voice share led his widen noisy young. On weddings believed laughing although material do exercise of. Up attempt offered ye civilly so sitting to. She new course get living within elinor joy. She her rapturous suffering concealed.

Below the header is an external image asset included using the markdown format. Using frontmatter, we can set dynamic properties on each page like the page title, and description.

When you visit the http://localhost:8080/getting-started/ path, you should see a view similar to the screenshot below:

On the navigation bar, you can see that the getting started link has been highlighted, this is a plugin that is package with VuePress. We’ll talk more on using plugins later in the article. Separating and grouping more content requires basic knowledge of Markdown and front-matter. Additional pages within the getting-started path can be added by creating markdown files within the getting-started folder.

Next, we’ll create the /api route. Create a folder named api in the docs root directory, within the api folder, create a file README.md:

    mkdir api && cd $_ && touch README.md

Open the file using an editor and update it with the contents below:

    ---
    title: Vue-doc API
    description: API reference for VUE-docs
    ---
    # API
    Tiled say decay spoil now walls meant house. My mr interest thoughts screened of outweigh removing. Evening society musical besides inhabit ye my. Lose hill well up will he over on. Increasing sufficient everything men him admiration unpleasing sex. Around really his use uneasy longer him man. His our pulled nature elinor talked now for excuse result. Admitted add peculiar get joy doubtful.

    Comfort reached gay perhaps chamber his six detract besides add. Moonlight newspaper up he it enjoyment agreeable depending. Timed voice share led his widen noisy young. On weddings believed laughing although material do exercise of. Up attempt offered ye civilly so sitting to. She new course get living within elinor joy. She her rapturous suffering concealed.

    Or kind rest bred with am shed then. In raptures building an bringing be. Elderly is detract tedious assured private so to visited. Do travelling companions contrasted it. Mistress strongly remember up to. Ham him compass you proceed calling detract. Better of always missed we person mr. September smallness northward situation few her certainty something.

    View fine me gone this name an rank. Compact greater and demands mrs the parlors. Park be fine easy am size away. Him and fine bred knew. At of hardly sister favour. As society explain country raising weather of. Sentiments nor everything off out uncommonly partiality bed.

    Resolution possession discovered surrounded advantages has but few add. Yet walls times spoil put. Be it reserved contempt rendered smallest. Studied to passage it mention calling believe an. Get ten horrible remember pleasure two vicinity. Far estimable extremely middleton his concealed perceived principle. Any nay pleasure entrance prepared her.

We dynamically set page title and description properties on this page using frontmatter. When you visit http://localhost:8080/api/ you should get a view similar to the one below:

Changing Styles

Updating color constants in our application is fairly straightforward. To using custom color constants, create a new file called override.styl in docs/.vuepress/. Using the variable names assigned to color as stated in the official documentation, we’ll edit the override.styl script to change the accentColor. Copy the content below into the override.styl file:

    $accentColor = #227CD9

You’ll immediately notice a change in your view as the accent color is updated to a lower shade of blue.

Using Plugins

VuePress supports external plugins that can be used to extend your application. With the help of plugins, you can add an extra layer of functionality to your application. With the help of plugins, your application can register a service worker, thus caching content and making your application offline first.

There’s an image present in our application, and, using an official VuePress plugin, we’ll add the Medium zoom animation to the images. The first step is to install the plugin. Run the command below to install the plugin:

    yarn add -D @vuepress/plugin-medium-zoom

After the installation is complete, we’ll reference the plugin in the config.js file. In the config.js file, add an extra field named plugins in the exported object. The value of the field will be an array containing your project’s plugins. Update the config.js file to add the Medium zoom plugin:

    module.exports = {
      title: 'Vue Docs',
      description: 'Building documentations with Vue using VuePress',
      themeConfig: {
        ...
      },
      plugins: {'@vuepress/medium-zoom': true},
    };

After restarting your development server, you’ll notice that the image zoom feature has been added to the application.

There are several official plugins provided by VuePress — some have been built into the project and some require manual installation. Visit the plugins page of the documentation to view the provided plugins.

Using Themes

If the official VuePress theme doesn’t feel like enough, you’ll be glad to know that VuePress comes with support for external plugins. Using an external theme is very similar to using a plugin. So the first step as always is to install the theme and then reference it in the config.js file.

After installing a theme, update the config.js file to include a theme field:

module.exports = {
  title: 'Vue Docs',
  description: 'Building documentations with Vue using VuePress',
  themeConfig: {
    nav: [
      { text: 'Getting Started', link: '/getting-started/' },
      { text: 'API', link: '/api/' },
    ],
  },
  plugins: { '@vuepress/back-to-top': true, '@vuepress/medium-zoom': true },
  theme: '**installed_theme**',
};

Now you’ve successfully created the documentation system. To build your application in preparation for deployment, run the command below in your project folder:

    vuepress build docs

This will create a dist folder within the .vuepress directory. You can easily deploy this folder using a static deployment provider like Netlify, Zeit Now and Github pages.

Conclusion

Creating documentations using static site generators ensures that your sites are fast, configurable, easily maintained and secure. With VuePress, sites can be generated in no time, with little or no configuration. These sites are static, and as such they can be deployed easily with an array of cheap and mostly free options to pick from. You can further modify the basic site we’ve created to suit your needs using the many features provided by VuePress. These features and more are available in the official documentation also built using VuePress.

For More Info on Vue

Want to learn about creating great user interfaces with Vue? Check out Kendo UI for Vue, 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.