Het schrijven van documentatie is eenvoudig geworden dankzij VuePress

Het is altijd een belangrijke kwestie geweest om een inspanning te leveren die nodig is om iets te ontwerpen, te programmeren en te implementeren dat aan verschillende criteria voldoet:

• kunt u snel naar de structuur van een toepassing gaan
• je kunt vrij zoeken in de inhoud
• biedt een reeks technische informatie over de gebruikte oplossingen
• ondersteunt opmaak van een tekst en een code
• kan worden opgeslagen op GitHub, bij voorkeur met een mogelijkheid tot eenvoudige implementatie.

Geen wonder dat de documentatie gepaard gaat met grote uitgaven. Aan de andere kant zijn de team groeit, brengt onboarding veel kosten met zich mee en daarvoor stelt support ontwikkelaars voortdurend dezelfde vragen. Op een gegeven moment mist iedereen ... VuePress.

VuePress is een statische paginagenerator gebaseerd op de Vue.js framework, wat geweldig is voor het maken van documentatie. Een goed voorbeeld kan worden gegeven door de documentatie van Vue.js zelf.

Met VuePress kun je teksten in het Markdown-formaat bewerken met behulp van Vue-componenten, die uiteindelijk een heel breed scala aan mogelijkheden bieden. Begin gewoon met twee commando's:

npm install -g vuepress

vuepress ontwikkeling

Standaard draait VuePress in de map docs / en maakt het daarin zijn eigen map vuepress aan. Na het invoeren van de bovenstaande commando's start het automatisch de Knooppunt server en geeft de documentatie weer op localhost: 8080 /. Hier is een voorbeeld van de bestandsstructuur.

Met de juiste configuratie genereert VuePress een complete en zeer esthetische pagina. Zoals je kunt zien op het scherm hierboven, bevat onze documentatie twee aangepaste componenten - CodeHeading en ColorSample.

Een eenvoudiger voorbeeld voor het begin is CodeHeading.

CodeKop.vue

Sjabloon:

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

Stijlen:

.code-heading {
 breedte: 100%;
 hoogte: 40px;
 regelhoogte: 40px;
 lettergrootte: 12px;
 marge-bodem: -20px;
 rand-top-links-radius: 6px;
 rand-top-rechts straal: 6px;
 tekst-uitlijning: links;
 opvulling: 0 20px;
 box-sizing: border-box;
 kleur: wit;

 &__bad {
   achtergrondkleur: #cc0000;

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

 &__good {
   achtergrondkleur: #3eaf7c;

   &::after {
     inhoud: "GOED";
   }
 }

 &__default {
   achtergrondkleur: #4e6e8e;
 }
}

Script:

export standaard {
 rekwisieten: {
   type: String
 },
 berekend: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Dit is een standaard syntaxis van een Vue.js component, die gemakkelijk beschikbaar is in Markdown bestanden. Hier is een voorbeeld van een implementatie (/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');

Op deze manier hebben we een volledig leesbare oplossing gekregen om voorbeelden van het werken met een code te presenteren.

Waarschijnlijk heeft elke frontend ontwikkelaar wel eens een situatie gehad waarin ze de HEX representatie van een kleur uit het grafisch ontwerp misten. En wat als je kleuren altijd bij de hand zou kunnen hebben en een bepaald palet van tevoren zou kunnen vastleggen? Dat klopt - documentatie zorgt er op de een of andere manier voor dat we ons aan de standaard houden. Het resultaat kan er als volgt uitzien:

In dit voorbeeld is het ColorPicker.vue component gebruikt. Het dient niet alleen voor de presentatie van een bepaalde kleur - door op een cirkel te klikken, kopiëren we automatisch de HEX-code naar het klembord.

Sjabloon:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Klik om HEX-code te kopiëren"
      >
        <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>(( naam ))</strong><br/>
        (( kleur ))
      </p>
    </div>
  </div>
</template>

Stijlen:

.kleurmonster {
 weergave: inline-block;
 breedte: 45%;
 marge: 15px;

 &__container {
   weergave: flex;
   uitlijnen-items: centreren;
 }

 &__cirkel {
   breedte: 70px;
   hoogte: 70px;
   zweven: links;
   grensradius: 50%;
   weergave: flex;
   uitlijnen-items: centreren;
   justify-content: centre;
   marge-rechts: 20px;
   cursor: aanwijzer;
   rand: 1px solid #cfd4db;
 }

 &__input-wrapper {
   positie: relatief;
 }

 &__input {
   lettergrootte: 12px;
   opvulling: 2px;
   grensradius: 2px;
   border: 0;
   weergave: inline-block;
   breedte: 60px;
 }

 &__input-overlay {
   positie: absoluut;
   top: 0;
   links: 0;
   rechts: 0;
   bottom: 0;
   achtergrondkleur: wit;
   tekst-uitlijning: centreren;
 }
}

Script:

export standaard {
 rekwisieten: {
   kleur: String,
   naam: String
 },
 berekend: {
   hexId() {
     return `kleur-${this.color.replace("#", "")}`;
   }
 },
 methoden: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Een voorbeeld van een implementatie (/docs/Design/colors.md):

Het is de moeite waard om aandacht te besteden aan de zoekmachine die is ingebouwd in VuePress:

Op basis van de headers in Markdown-bestanden werkt het automatisch. De configuratie van de documentatie op deze manier gaat als volgt:

module.exports = {
 titel: 'Docs',
 themaConfig: {
   zijbalk: [
     {
       titel: 'Algemeen
       inklapbaar: false,
       kinderen: [
         "Algemeen/introductie.md",
         Algemeen/installatie.md
       ]
     },
     {
       titel: 'Ontwerp
       collapsable: false,
       kinderen: [
         "Ontwerp/kleuren.md",
         ontwerp/lettertypen.md
         ontwerp/formulieren.md
         ontwerp/layout.md
       ]
     },
     {
       titel: "Code
       collapsable: false,
       kinderen: [
         'Code/general.md',
         Code/javascript.md
         'Code/scss.md',
         Code/vue.md
         'Code/vertalingen.md',
         Code/git.md
         Code/deployment.md
       ]
     }
   ],
   nav: [
     {
       tekst: 'Kennis
       items: [
         {tekst: "VueSchools", link: 'https://vueschool.io/' }
       ]
     },
     {
       tekst: "Codest",
       link: 'https://codesthq.com'
     },
     {
       tekst: 'Docs op GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Met de vuepress bouwen commando kunnen we direct statische HTML-bestanden genereren die klaar zijn voor snelle publicatie met volledige ondersteuning voor bedrijfsmiddelen.

Het is het vermelden waard dat VuePress een automatische implementatie op verschillende platforms toestaat, waaronder GitHub Pages. Daarnaast maakt de mogelijkheid om je eigen thema's te maken VuePress tot een goede blogoplossing.

Als de bovenstaande voorbeelden je nieuwsgierigheid hebben gewekt, raad ik je aan om voor meer informatie kennis te maken met de officiële documentatie van de VuePress project.

Lees meer:

• Code optimaliseren met Query-objecten
• Vue.js basistutorial. Hoe begin je met dit framework?
• Beveiliging in Javascript-pakketten
• GraphQL: geleerde lessen in productie