Escribir documentación es ahora más fácil gracias a VuePress

Siempre ha sido una cuestión importante hacer el esfuerzo necesario para diseñar, programar y aplicar algo que cumpla varios criterios:

• permite acceder rápidamente a la estructura de una aplicación
• le permite buscar libremente en el contenido
• proporciona información técnica sobre las soluciones utilizadas
• permite formatear un texto y un código
• puede almacenarse en GitHub, preferiblemente con posibilidad de despliegue fácil.

No es de extrañar que la documentación vaya asociada a grandes gastos. Por otra parte, la equipo está creciendo, la incorporación genera muchos costes, y para ello el servicio de asistencia hace constantemente las mismas preguntas a los desarrolladores. En algún momento, todo el mundo echa de menos ... VuePress.

VuePress es un generador de páginas estáticas basado en la tecnología Vue.js, que es ideal para crear documentación. Un buen ejemplo puede ser la propia documentación de Vue.js.

VuePress te permite editar textos en formato Markdown con el uso de los componentes de Vue, que, por último, ofrecen un abanico de posibilidades realmente amplio. Basta con empezar con dos comandos:

npm install -g vuepress

vuepress dev

Por defecto, VuePress se ejecuta en el directorio docs / y crea su propia carpeta. vuepress en ella. Después de introducir los comandos anteriores, se inicia automáticamente el Nodo y muestra la documentación en localhost: 8080 /. He aquí un ejemplo de la estructura del archivo.

Con una configuración adecuada, VuePress generará una página completa y muy estética. Como se puede ver en la pantalla de arriba, nuestra documentación contiene dos componentes personalizados - CodeHeading y ColorSample.

Un ejemplo más sencillo para empezar será CodeHeading.

CodeHeading.vue

Plantilla:

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

Estilos:

.code-heading {
 anchura: 100%;
 altura: 40px;
 altura de línea: 40px;
 font-size: 12px;
 margin-bottom: -20px;
 borde superior izquierdo: 6px;
 borde superior-derecho-radio: 6px;
 alineación del texto: izquierda;
 relleno: 0 20px;
 box-sizing: border-box;
 color: blanco;

 &__bad {
   color de fondo: #cc0000;

   &::after {
     contenido: "MALO";
   }
 }

 &__bueno {
   color de fondo: #3eaf7c;

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

 &__default {
   color de fondo: #4e6e8e;
 }
}

Guión:

exportar por defecto {
 accesorios: {
   tipo: Cadena
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Se trata de una sintaxis estándar de un componente Vue.js, fácilmente disponible en archivos Markdown. Aquí tienes un ejemplo de implementación (/docs/Code/javacript.md):

const valueWrappers = wrapper.findAll('.change__value').wrappers;
esperar(valueWrappers).tener.lengthOf(2);

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

De este modo, hemos obtenido una solución totalmente legible para presentar ejemplos de trabajo con un código.

Probablemente todos los desarrolladores frontend se han encontrado alguna vez en una situación en la que les faltaba la representación HEX de algún color del diseño gráfico. ¿Y si pudieras tener siempre a mano el color y fijar de antemano una determinada paleta? Así es: la documentación nos obliga de algún modo a ceñirnos al estándar. El resultado puede parecerse al siguiente:

En este ejemplo se ha utilizado el componente ColorPicker.vue. Sirve no sólo para la presentación de un color dado - haciendo clic en un círculo, copiaremos automáticamente el código HEX en el portapapeles.

Plantilla:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Haga clic para copiar el código HEX"
      >
        <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>(( nombre ))</strong><br/>
        (( color ))
      </p>
    </div>
  </div>
</template>

Estilos:

.color-muestra {
 display: inline-block;
 anchura: 45%;
 margin: 15px;

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

 &__circle {
   ancho: 70px;
   altura: 70px;
   float: izquierda;
   border-radius: 50%;
   mostrar: flex;
   align-items: center;
   justify-content: center;
   margen-derecha: 20px;
   cursor: puntero;
   borde: 1px solid #cfd4db;
 }

 &__input-wrapper {
   posición: relativa;
 }

 &__input {
   font-size: 12px;
   relleno: 2px
   border-radius: 2px;
   borde: 0;
   visualización: inline-block;
   anchura: 60px;
 }

 &__input-overlay {
   posición: absoluta;
   top: 0;
   izquierda: 0
   derecha: 0
   inferior: 0;
   color de fondo: blanco;
   text-align: center;
 }
}

Guión:

exportar por defecto {
 accesorios: {
   color: String,
   nombre: cadena
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 métodos: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copiar");
   }
 }
};

Un ejemplo de implementación (/docs/Design/colors.md):

Merece la pena prestar atención al motor de búsqueda incorporado en VuePress:

Basándose en las cabeceras de los archivos Markdown, funciona automáticamente. La configuración de la documentación hecha de esta manera viene como sigue:

module.exports = {
 title: 'Docs',
 themeConfig: {
   barra lateral: [
     {
       title: 'General',
       colapsable: false,
       niños: [
         General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title: 'Diseño',
       collapsable: false,
       hijos: [
         'Diseño/colores.md',
         'Diseño/fonts.md',
         'Diseño/formularios.md',
         Diseño/diseño.md
       ]
     },
     {
       title: 'Código',
       collapsable: false,
       hijos: [
         'Código/general.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         Code/git.md,
         Code/deployment.md
       ]
     }
   ],
   nav: [
     {
       text: 'Conocimiento',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       enlace: 'https://github.com/'
     }
   ]
 }
}

Con la vuepress construya podemos generar al instante archivos HTML estáticos listos para su rápida publicación con total compatibilidad de activos.

Vale la pena mencionar que VuePress permite un despliegue automático en varias plataformas, incluyendo GitHub Pages. Además, la posibilidad de crear tus propios temas hace de VuePress una solución de blog bastante buena.

Si los ejemplos anteriores han despertado tu curiosidad, para más información te recomiendo que te familiarices con la documentación oficial del VuePress proyecto.

Más información:

• Optimización del código con objetos de consulta
• Tutorial básico de Vue.js. Cómo empezar con este framework?
• Seguridad en los paquetes Javascript
• GraphQL: lecciones aprendidas en producción