Att skriva dokumentation har blivit enkelt tack vare VuePress
Wojciech Bak
Att skriva dokumentation är en standard som i många projekt blir en lyx. Produktionen av den hamnar lätt i bakgrunden, särskilt när nästa prioritet ges till ytterligare funktioner i fasen för dynamisk applikationsutveckling.
Det har alltid varit en viktig fråga att anstränga sig för att utforma, programmera och implementera något som uppfyller flera kriterier:
gör att du snabbt kan komma till strukturen i en applikation
ger dig möjlighet att fritt söka i innehållet
ger en uppsättning teknisk information om de lösningar som används
kan lagras på GitHub, helst med möjlighet till enkel utplacering.
Det är inte konstigt att dokumentationen är förknippad med stora kostnader. Å andra sidan är Team växer genererar onboarding en hel del kostnader, och därför ställer supporten ständigt samma frågor till utvecklarna. Vid någon tidpunkt saknar alla ... VuePress.
VuePress är en statisk sidgenerator baserad på Vue.js-ramverket, vilket är utmärkt för att skapa dokumentation. Ett bra exempel kan ställas in av dokumentationen av Vue.js själv.
VuePress låter dig redigera texter i Markdown-format med hjälp av Vue-komponenter, som slutligen ger ett riktigt brett utbud av möjligheter. Börja bara med två kommandon:
npm installera -g vuepress
vuepress dev
Som standard körs VuePress på docs / katalogen och skapar sin egen. vuepress-mapp i den. När du har angett ovanstående kommandon startar den automatiskt Nod servern och visar dokumentationen på localhost: 8080 /. Här följer ett exempel på filstrukturen.
Med en korrekt konfiguration kommer VuePress att generera en komplett och mycket estetisk sida. Som du kan se på skärmen ovan innehåller vår dokumentation två anpassade komponenter - CodeHeading och ColorSample.
Ett enklare exempel till en början är CodeHeading.
Detta är en standardsyntax för en Vue.js-komponent, som är lätt tillgänglig i Markdown-filer. Här är ett exempel på en implementering (/docs/Code/javacript.md):
På så sätt har vi fått en helt läsbar lösning för att presentera exempel på hur man arbetar med en kod.
Förmodligen har alla frontend-utvecklare varit med om en situation där de saknade HEX-representationen av en färg från den grafiska designen. Och tänk om man alltid kunde ha färgerna till hands och fixa en viss palett i förväg? Det stämmer - dokumentation får oss på något sätt att hålla oss till standarden. Resultatet kan se ut på följande sätt:
I det här exemplet användes komponenten ColorPicker.vue. Den tjänar inte bara till att presentera en viss färg - genom att klicka på en cirkel kopierar vi automatiskt HEX-koden till urklippet.
Mall:
<template>
<div class="color-sample">
<div class="color-sample__container">
<div
class="color-sample__circle"
@click="copyToClipboard"
:style="`background-color: ${ color }`"
title="Klicka för att kopiera 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>(( namn ))</strong><br/>
(( färg ))
</p>
</div>
</div>
</template>
Med vuepressbygga command kan vi direkt generera statiska HTML-filer som är redo för snabb publicering med fullt stöd för tillgångar.
Det är värt att nämna att VuePress tillåter en automatisk distribution på olika plattformar, inklusive GitHub Pages. Dessutom gör möjligheten att skapa dina egna teman VuePress till en ganska bra blogglösning.
Om ovanstående exempel väckte din nyfikenhet, för mer information rekommenderar jag att du bekantar dig med den officiella dokumentationen av VuePress projekt.