Det har blitt enkelt å skrive dokumentasjon takket være VuePress

Det har alltid vært viktig å gjøre en innsats for å utforme, programmere og implementere noe som oppfyller flere kriterier:

• lar deg raskt komme til strukturen i en applikasjon
• lar deg søke fritt i innholdet
• gir et sett med teknisk informasjon om de brukte løsningene
• støtter formatering av en tekst og en kode
• kan lagres på GitHub, helst med mulighet for enkel distribusjon.

Det er ikke rart at dokumentasjonen er forbundet med store utgifter. På den annen side er team vokser, genererer onboarding store kostnader, og derfor stiller supporten stadig de samme spørsmålene til utviklerne. På et eller annet tidspunkt savner alle ... VuePress.

VuePress er en statisk sidegenerator basert på Vue.js-rammeverket, som er ypperlig til å lage dokumentasjon. Et godt eksempel er dokumentasjonen av selve Vue.js.

Med VuePress kan du redigere tekster i Markdown-formatet ved hjelp av Vue-komponenter, som til slutt gir et veldig bredt spekter av muligheter. Bare begynn med to kommandoer:

npm install -g vuepress

vuepress dev

Som standard kjører VuePress på docs / -katalogen og oppretter sin egen. vuepress-mappe i den. Når du har angitt kommandoene ovenfor, starter den automatisk Knutepunkt serveren og viser dokumentasjonen på localhost: 8080 /. Her er et eksempel på filstrukturen.

Med riktig konfigurasjon vil VuePress generere en komplett og svært estetisk side. Som du kan se på skjermen ovenfor, inneholder dokumentasjonen vår to tilpassede komponenter - CodeHeading og ColorSample.

Et enklere eksempel til å begynne med er CodeHeading.

CodeHeading.vue

Mal:

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

Stiler:

.code-heading {
 bredde: 100%;
 høyde: 40px;
 linjehøyde: 40px;
 skriftstørrelse: 12px;
 margin-bunn: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 tekstjustering: venstre;
 padding: 0 20px;
 box-sizing: border-box;
 farge: hvit;

 &__bad {
   bakgrunnsfarge: #cc0000;

   &::after {
     innhold: "BAD";
   }
 }

 &__good {
   bakgrunnsfarge: #3eaf7c;

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

 &__default {
   bakgrunnsfarge: #4e6e8e;
 }
}

Manus:

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

Dette er en standard syntaks for en Vue.js-komponent, som er lett tilgjengelig 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å denne måten har vi fått en fullstendig lesbar løsning for å presentere eksempler på arbeid med en kode.

Alle frontend-utviklere har nok opplevd å mangle HEX-representasjonen av en farge fra det grafiske designet. Og hva om du alltid kunne ha farger for hånden og fastsette en bestemt palett på forhånd? Det stemmer - dokumentasjon får oss på en eller annen måte til å holde oss til standarden. Resultatet kan se ut som følger:

I dette eksemplet ble komponenten ColorPicker.vue brukt. Den tjener ikke bare til å presentere en gitt farge - ved å klikke på en sirkel kopierer vi automatisk HEX-koden til utklippstavlen.

Mal:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Klikk for å kopiere HEX-kode"
      >
        <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/>
        (( farge )))
      </p>
    </div>
  </div>
</template>

Stiler:

.color-sample {
 display: inline-block;
 bredde: 45%;
 margin: 15px;

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

 &__circle {
   bredde: 70px;
   høyde: 70 piksler;
   float: left;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-høyre: 20px;
   markør: peker;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   posisjon: relativ;
 }

 &__input {
   font-size: 12px;
   padding: 2px;
   border-radius: 2px;
   border: 0;
   display: inline-block;
   bredde: 60px;
 }

 &__input-overlay {
   posisjon: absolutt;
   top: 0;
   left: 0; left: 0
   right: 0;
   bottom: 0;
   bakgrunnsfarge: hvit;
   tekstjustering: midt;
 }
}

Manus:

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 verdt å være oppmerksom på søkemotoren som ble bygget i VuePress:

Basert på overskriftene i Markdown-filer fungerer det automatisk. Konfigurasjonen av dokumentasjonen som er laget på denne måten, er som følger:

module.exports = {
 title: 'Docs',
 themeConfig: {
   sidefelt: [
     {
       tittel: 'General',
       sammenleggbar: false,
       children: [
         'General/introduction.md',
         'Generelt/installasjon.md'
       ]
     },
     {
       title: 'Design',
       sammenleggbar: false,
       children: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md', 'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title: 'Kode',
       sammenleggbar: false,
       children: [
         'Kode/generell.md',
         "Kode/javascript.md", "Kode/scss.md
         "Kode/scss.md", "Kode/vue.md
         "Kode/vue.md",
         "Kode/oversettelser.md", "Kode/git.md",
         "Kode/git.md",
         "Kode/deployment.md
       ]
     }
   ],
   nav: [
     {
       text: "Kunnskap",
       elementer: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       tekst: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       tekst: "Dokumenter på GitHub",
       link: 'https://github.com/'
     }
   ]
 }
}

Med vuepress bygge kommandoen kan vi umiddelbart generere statiske HTML-filer som er klare for rask publisering med full støtte for ressurser.

Det er verdt å nevne at VuePress tillater automatisk distribusjon på ulike plattformer, inkludert GitHub Pages. I tillegg gjør muligheten til å lage dine egne temaer VuePress til en ganske god bloggløsning.

Hvis eksemplene ovenfor vekket nysgjerrigheten din, anbefaler jeg deg å lese den offisielle dokumentasjonen til VuePress for mer informasjon prosjekt.

Les mer om dette:

• Optimalisering av kode med Query Objects
• Vue.js grunnleggende opplæring. Hvordan starte med dette rammeverket?
• Sikkerhet i Javascript-pakker
• GraphQL: Erfaringer fra produksjon