Writing documentation has become easy thanks to VuePress

It has always been an important issue to make an effort necessary to design, program and implement something that meets several criteria:

• allows you to quickly get to the structure of an application
• allows you to freely search the content
• provides a set of technical information on the used solutions
• supports formatting of a text and a code
• can be stored on GitHub, preferably with a possibility of easy deployment.

No wonder that the documentation is associated with large expenses. On the other hand, the team is growing, onboarding generates a lot of costs, and for that support constantly asks developers the same questions. At some point, everyone is missing … VuePress.

VuePress is a static page generator based on the Vue.js framework, which is great for creating documentation. A good example can be set by the documentation of Vue.js itself.

VuePress allows you to edit texts in the Markdown format with the usage of Vue components, which, finally, give a really wide range of possibilities. Just start with two commands:

npm install -g vuepress

vuepress dev

By default, VuePress runs on the docs / directory and creates its own. vuepress folder in it. After entering the above commands, it automatically starts the Node server and displays the documentation at localhost: 8080 /. Here is an example of the file structure.

With a proper configuration, VuePress will generate a complete and very aesthetic page. As you can see on the screen above, our documentation contains two custom components – CodeHeading and ColorSample.

A simpler example for the beginning will be CodeHeading.

CodeHeading.vue

Template:

<template>
  <div :class="[ 'code-heading', colorClass ]">
    <slot/>
  </div>
</template>

Styles:

.code-heading {
 width: 100%;
 height: 40px;
 line-height: 40px;
 font-size: 12px;
 margin-bottom: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 text-align: left;
 padding: 0 20px;
 box-sizing: border-box;
 color: white;

 &__bad {
   background-color: #cc0000;

   &::after {
     content: "BAD";
   }
 }

 &__good {
   background-color: #3eaf7c;

   &::after {
     content: "GOOD";
   }
 }

 &__default {
   background-color: #4e6e8e;
 }
}

Script:

export default {
 props: {
   type: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

This is a standard syntax of a Vue.js component, which is easily available in Markdown files. Here’s an example of an implementation (/docs/Code/javacript.md):

const valueWrappers = wrapper.findAll('.change__value').wrappers;
expect(valueWrappers).to.have.lengthOf(2);

expect(valueWrappers[0].text()).to.equal('€ 5000');
expect(valueWrappers[1].text()).to.equal('0');

In this way, we have received a completely legible solution to present examples of working with a code.

Probably every frontend developer has had a situation where they lacked the HEX representation of any colour from the graphics design. And what if you could always have colour at hand and fix a certain palette in advance? That’s right – documentation somehow makes us stick to the standard. The result may look like the following:

In this example, the ColorPicker.vue component was used. It serves not only the presentation of a given colour – by clicking on a circle, we will automatically copy the HEX code to the clipboard.

Template:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Click to copy HEX code"
      >
        <div class="color-sample__input-wrapper">
          <input type="text" class="color-sample__input" :id="hexId" :value="color">
            <div class="color-sample__input-overlay" :style="`background-color: ${ color }`"></div>
        </div>
      </div>
      <p>
        <strong>(( name ))</strong><br/>
        (( color ))
      </p>
    </div>
  </div>
</template>

Styles:

.color-sample {
 display: inline-block;
 width: 45%;
 margin: 15px;

 &__container {
   display: flex;
   align-items: center;
 }

 &__circle {
   width: 70px;
   height: 70px;
   float: left;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-right: 20px;
   cursor: pointer;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relative;
 }

 &__input {
   font-size: 12px;
   padding: 2px;
   border-radius: 2px;
   border: 0;
   display: inline-block;
   width: 60px;
 }

 &__input-overlay {
   position: absolute;
   top: 0;
   left: 0;
   right: 0;
   bottom: 0;
   background-color: white;
   text-align: center;
 }
}

Script:

export default {
 props: {
   color: String,
   name: String
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 methods: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

An example of an implementation (/docs/Design/colors.md):

<color-sample color="#000000" name="$color-black" />
<color-sample color="#FFFFFF" name="$color-white" /> 

It is worth paying attention to the search engine that was built in VuePress:

Based on the headers in Markdown files it works automatically. The configuration of the documentation made this way comes as following:

module.exports = {
 title: 'Docs',
 themeConfig: {
   sidebar: [
     {
       title: 'General',
       collapsable: false,
       children: [
         'General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title: 'Design',
       collapsable: false,
       children: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title: 'Code',
       collapsable: false,
       children: [
         'Code/general.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         'Code/git.md',
         'Code/deployment.md'
       ]
     }
   ],
   nav: [
     {
       text: 'Knowledge',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

With the vuepress build command, we can instantly generate static HTML files ready for quick publication with full asset support.

It is worth mentioning that VuePress allows an automatic deployment on various platforms, including GitHub Pages. In addition, the ability to create your own themes makes VuePress quite a good blog solution.

If the above examples aroused your curiosity, for more information I recommend you to get acquainted with official documentation of the VuePress project.

Read more:

• Optimizing code with Query Objects
• Vue.js basics tutorial. How to start with this framework?
• Security in Javascript packages
• GraphQL: lessons learned in production