Att skriva dokumentation har blivit enkelt tack vare VuePress

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
• stöder formatering av en text och en kod
• 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 ges 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.

CodeHeading.vue

Mall:

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

Stilar:

.kod-rubrik {
 bredd: 100%;
 höjd: 40px;
 radhöjd: 40px;
 teckenstorlek: 12px;
 marginal-botten: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 text-align: left;
 stoppning: 0 20px;
 box-storlek: border-box;
 färg: vit;

 &__bad {
   bakgrundsfärg: #cc0000;

   &::efter {
     innehåll: "BAD";
   }
 }

 &__god {
   bakgrundsfärg: #3eaf7c;

   &::efter {
     innehåll: "GOOD";
   }
 }

 &__standard {
   bakgrundsfärg: #4e6e8e;
 }
}

Skript:

export standard {
 rekvisita: {
   typ: Sträng
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

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

const valueWrappers = wrapper.findAll('.change__value').wrappers;
förväntar sig(valueWrappers).att.ha.lengthOf(2);

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

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>

Stilar:

.färgprov {
 display: inline-block;
 bredd: 45%;
 marginal: 15px;

 &__behållare {
   display: flex;
   align-items: center;
 }

 &__cirkel {
   bredd: 70px;
   höjd: 70px;
   float: vänster;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-innehåll: center;
   marginal-höger: 20px;
   markör: pekare;
   kant: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relativ;
 }

 &__input {
   teckenstorlek: 12px;
   stoppning: 2px;
   border-radius: 2px;
   gräns: 0;
   display: inline-block;
   bredd: 60 pixlar;
 }

 &__input-overlay {
   position: absolut;
   topp: 0;
   vänster: 0;
   höger: 0;
   botten: 0;
   bakgrundsfärg: vit;
   textjustering: mitten;
 }
}

Skript:

export standard {
 rekvisita: {
   färg: String,
   namn: sträng
 },
 computed: {
   hexId() {
     return `färg-${this.color.replace("#", "")}`;
   }
 },
 metoder: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     etikett.välj();
     document.execCommand("copy");
   }
 }
};

Ett exempel på en implementering (/docs/Design/colors.md):

Det är värt att uppmärksamma den sökmotor som byggdes i VuePress:

Baserat på rubrikerna i Markdown-filer fungerar det automatiskt. Konfigurationen av dokumentationen som görs på detta sätt ser ut enligt följande:

modul.export = {
 titel: 'Docs',
 temaConfig: {
   sidofält: [
     {
       titel: "Allmänt",
       hopfällbar: false,
       barn: [
         'Allmänt/introduktion.md',
         'Allmänt/installation.md'
       ]
     },
     {
       titel: "Design",
       hopfällbar: falsk,
       barn: [
         'Design/färger.md',
         "Design/fonts.md", "Design/forms.md
         "Design/forms.md", "Design/forms.md
         "Design/layout.md
       ]
     },
     {
       titel: "Kod",
       hopfällbar: false,
       barn: [
         'Kod/allmänt.md',
         'Kod/javascript.md',
         "Kod/scss.md", "Kod/vue.md
         'Kod/vue.md',
         "Kod/översättningar.md", "Kod/git.md
         "Kod/git.md",
         "Kod/deployment.md
       ]
     }
   ],
   nav: [
     {
       text: "Kunskap",
       objekt: [
         { text: 'VueSchools', länk: 'https://vueschool.io/' }
       ]
     },
     {
       text: "Codest",
       länk: 'https://codesthq.com'
     },
     {
       text: "Dokument på GitHub",
       länk: 'https://github.com/'
     }
   ]
 }
}

Med vuepress bygga 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.

Läs mer om detta:

• Optimera kod med Query Objects
• Vue.js grunderna handledning. Hur börjar man med detta ramverk?
• Säkerhet i Javascript-paket
• GraphQL: lärdomar från produktion