Go to content
The Codest
  • About Us
    • Staff Augmentation
    • Project Development
    • Cloud Engineering
    • Quality Assurance
    • Web Development
  • Our Team
  • Case studies
    • Blog
    • Meetups
    • Webinars
    • Resources
Careers Get in touch
  • About Us
    • Staff Augmentation
    • Project Development
    • Cloud Engineering
    • Quality Assurance
    • Web Development
  • Our Team
  • Case studies
    • Blog
    • Meetups
    • Webinars
    • Resources
Careers Get in touch
2019-04-02
Software Development

Writing documentation has become easy thanks to VuePress

Wojciech Bak

Writing documentation has become easy thanks to VuePress - Image

Writing documentation is a standard that in many projects becomes a luxury. Its production easily goes into the background, especially when the next priority is given to the further functionalities at the phase of dynamic application development.

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

Related articles

Software Development

3 Useful HTML Tags You Might Not Know Even Existed

Nowadays, accessibility (A11y) is crucial on all stages of building custom software products. Starting from the UX/UI design part, it trespasses into advanced levels of building features in code. It provides tons of benefits for...

Jacek Ludzik
Software Development

5 examples of Ruby’s best usage

Have you ever wondered what we can do with Ruby? Well, the sky is probably the limit, but we are happy to talk about some more or less known cases where we can use this powerful language. Let me give you some examples.

Pawel Muszynski
Software Development

Maintaining a Project in PHP: 5 Mistakes to Avoid

More than one article has been written about the mistakes made during the process of running a project, but rarely does one look at the project requirements and manage the risks given the technology chosen.

Sebastian Luczak
Software Development

Why you will find qualified Ruby developers in Poland?

Real Ruby professionals are rare birds on the market. Ruby is not the most popular technology, so companies often struggle with the problem of finding developers who have both high-level skills and deep experience; oh, and by the...

Jakub
Software Development

9 Mistakes to Avoid While Programming in Java

What mistakes should be avoided while programming in Java? In the following piece we answers this question.

Rafal Sawicki
Software Development

A quick dive into Ruby 2.6. What is new?

Released quite recently, Ruby 2.6 brings a bunch of conveniences that may be worth taking a glimpse of.  What is new? Let’s give it a shot!

Patrycja Slabosz

Subscribe to our knowledge base and stay up to date on the expertise from industry.

About us

The Codest – International Tech Software Company with tech hubs in Poland.

    United Kingdom - Headquarters

  • Office 303B, 182-184 High Street North E6 2JA London, England

    Poland - Local Tech Hubs

  • Business Link High5ive, Pawia 9, 31-154 Kraków, Poland
  • Brain Embassy, Konstruktorska 11, 02-673 Warsaw, Poland
  • Aleja Grunwaldzka 472B, 80-309 Gdańsk, Poland

    The Codest

  • Home
  • About us
  • Services
  • Case studies
  • Know how
  • Careers

    Services

  • PHP development
  • Java development
  • Python development
  • Ruby on Rails development
  • React Developers
  • Vue Developers
  • TypeScript Developers
  • DevOps
  • QA Engineers

    Resources

  • What are top CTOs and CIOs Challenges? [2022 updated]
  • Facts and Myths about Cooperating with External Software Development Partner
  • From the USA to Europe: Why do American startups decide to relocate to Europe
  • Privacy policy
  • Website terms of use

Copyright © 2022 by The Codest. All rights reserved.

We use cookies on the site for marketing, analytical and statistical purposes. By continuing to use, without changing your privacy settings, our site, you consent to the storage of cookies in your browser. You can always change the cookie settings in your browser. You can find more information in our Privacy Policy.