Det er blevet nemt at skrive dokumentation takket være VuePress

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
• understøtter formatering af en tekst og en Kode
• 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 er en statisk sidegenerator baseret på Vue.js-framework, som er fantastisk til at skabe dokumentation. Et godt eksempel er selve dokumentationen af Vue.js.

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.

Kodeoverskrift.vue

Skabelon:

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

Stilarter:

.kode-overskrift {
 bredde: 100%;
 højde: 40px;
 linjehøjde: 40 px;
 skriftstørrelse: 12px;
 margin-bottom: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 tekstjustering: venstre;
 padding: 0 20px;
 box-sizing: border-box;
 farve: hvid;

 &__bad {
   baggrundsfarve: #cc0000;

   &::efter {
     indhold: "BAD";
   }
 }

 &__god {
   baggrundsfarve: #3eaf7c;

   &::efter {
     indhold: "GOOD";
   }
 }

 &__standard {
   baggrundsfarve: #4e6e8e;
 }
}

Manuskript:

eksport standard {
 props: {
   type: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

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

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');

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>

Stilarter:

.farveprøve {
 display: inline-block;
 bredde: 45%;
 margin: 15px;

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

 &__cirkel {
   bredde: 70px;
   højde: 70px;
   float: venstre;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-right: 20px;
   cursor: pointer;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relativ;
 }

 &__input {
   skriftstørrelse: 12px;
   polstring: 2px;
   border-radius: 2px;
   border: 0;
   display: inline-block;
   bredde: 60 px;
 }

 &__input-overlay {
   position: absolut;
   top: 0;
   left: 0;
   right: 0;
   bottom: 0;
   baggrundsfarve: hvid;
   tekstjustering: center;
 }
}

Manuskript:

eksport standard {
 rekvisitter: {
   color: String,
   navn: String
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 metoder: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Et eksempel på en implementering (/docs/Design/colors.md):

.
. 

Det er værd at være opmærksom på den søgemaskine, der er indbygget i VuePress:

Baseret på overskrifterne i Markdown-filer fungerer det automatisk. Konfigurationen af dokumentationen lavet på denne måde ser ud som følger:

module.exports = {
 titel: 'Docs',
 themeConfig: {
   sidebar: [
     {
       titel: 'Generelt',
       collapsable: false,
       børn: [
         'General/introduction.md',
         'Generelt/installation.md'
       ]
     },
     {
       titel: 'Design',
       collapsable: false,
       børn: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       titel: 'Kode',
       collapsable: false,
       børn: [
         'Kode/generelt.md',
         'Kode/javascript.md',
         'Kode/scss.md',
         'Kode/vue.md',
         "Kode/oversættelser.md",
         "Kode/git.md",
         'Kode/implementering.md'
       ]
     }
   ],
   nav: [
     {
       tekst: 'Viden',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       tekst: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Dokumenter på GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Med den vuepress bygge 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.

Læs mere om det:

• Optimering af kode med Query Objects
• Grundlæggende vejledning i Vue.js. Hvordan kommer man i gang med dette framework?
• Sikkerhed i Javascript-pakker
• GraphQL: erfaringer fra produktion