Det er blevet nemt at skrive dokumentation takket være VuePress
Wojciech Bak
At skrive dokumentation er en standard, som i mange projekter bliver en luksus. Produktionen af den går let i baggrunden, især når den næste prioritet er de yderligere funktionaliteter i fasen med dynamisk applikationsudvikling.
Det har altid været vigtigt at gøre en indsats for at designe, programmere og implementere noget, der opfylder flere kriterier:
giver dig mulighed for hurtigt at komme til strukturen i en applikation
giver dig mulighed for frit at søge i indholdet
giver en række tekniske oplysninger om de anvendte løsninger
kan gemmes på GitHub, helst med mulighed for nem udrulning.
Det er ikke underligt, at dokumentationen er forbundet med store udgifter. På den anden side er hold vokser, genererer onboarding en masse omkostninger, og derfor stiller supporten konstant de samme spørgsmål til udviklerne. På et tidspunkt mangler alle ... 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 giver dig mulighed for at redigere tekster i Markdown-formatet ved hjælp af Vue-komponenter, som endelig giver en virkelig bred vifte af muligheder. Start bare med to kommandoer:
npm install -g vuepress
vuepress dev
Som standard kører VuePress i docs/mappen og opretter sin egen vuepress-mappe i den. Når du har indtastet ovenstående kommandoer, starter den automatisk Knudepunkt server og viser dokumentationen på localhost: 8080 /. Her er et eksempel på filstrukturen.
Med en korrekt konfiguration vil VuePress generere en komplet og meget æstetisk side. Som du kan se på skærmen ovenfor, indeholder vores dokumentation to brugerdefinerede komponenter - CodeHeading og ColorSample.
Et enklere eksempel til at begynde med er CodeHeading.
Dette er en standardsyntaks for en Vue.js-komponent, som er let tilgængelig i Markdown-filer. Her er et eksempel på en implementering (/docs/Code/javacript.md):
På den måde har vi fået en helt læsbar løsning til at præsentere eksempler på arbejdet med en kode.
Alle frontend-udviklere har sikkert prøvet at stå i en situation, hvor de manglede HEX-repræsentationen af en farve fra det grafiske design. Og hvad nu, hvis man altid kunne have en farve ved hånden og fastsætte en bestemt palet på forhånd? Det er rigtigt - dokumentation får os på en eller anden måde til at holde os til standarden. Resultatet kan se ud som følger:
I dette eksempel blev komponenten ColorPicker.vue brugt. Den tjener ikke kun til at præsentere en given farve - ved at klikke på en cirkel kopierer vi automatisk HEX-koden til udklipsholderen.
Skabelon:
<template>
<div class="color-sample">
<div class="color-sample__container">
<div
class="color-sample__circle"
@click="copyToClipboard"
:style="`background-color: ${ color }`"
title="Klik for at kopiere HEX-koden"
>
<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>(( navn ))</strong><br/>
(( farve ))
</p>
</div>
</div>
</template>
Med den vuepressbygge kommando, kan vi øjeblikkeligt generere statiske HTML-filer, der er klar til hurtig offentliggørelse med fuld understøttelse af aktiver.
Det er værd at nævne, at VuePress giver mulighed for automatisk udrulning på forskellige platforme, herunder GitHub Pages. Derudover gør muligheden for at skabe dine egne temaer VuePress til en ganske god blogløsning.
Hvis ovenstående eksempler har vakt din nysgerrighed, anbefaler jeg, at du læser den officielle dokumentation for VuePress for at få flere oplysninger. projekt.