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