Das Schreiben von Dokumentationen ist dank VuePress einfach geworden

Es war schon immer ein wichtiges Thema, die notwendigen Anstrengungen zu unternehmen, um etwas zu entwerfen, zu programmieren und umzusetzen, das mehrere Kriterien erfüllt:

• ermöglicht Ihnen einen schnellen Zugriff auf die Struktur einer Anwendung
• ermöglicht Ihnen die freie Suche im Inhalt
• bietet eine Reihe von technischen Informationen über die verwendeten Lösungen
• unterstützt die Formatierung eines Textes und einer Code
• kann auf GitHub gespeichert werden, vorzugsweise mit der Möglichkeit einer einfachen Bereitstellung.

Kein Wunder, dass die Dokumentation mit hohen Kosten verbunden ist. Auf der anderen Seite ist die Team wächst, verursacht das Onboarding eine Menge Kosten, und deshalb stellt der Support den Entwicklern immer wieder die gleichen Fragen. Irgendwann wird jeder vermisst ... VuePress.

VuePress ist ein Generator für statische Seiten, der auf dem Vue.js-Framework, das sich hervorragend für die Erstellung von Dokumentation eignet. Ein gutes Beispiel ist die Dokumentation von Vue.js selbst.

VuePress ermöglicht es Ihnen, Texte im Markdown-Format mit Hilfe von Vue-Komponenten zu bearbeiten, die Ihnen eine breite Palette von Möglichkeiten bieten. Beginnen Sie einfach mit zwei Befehlen:

npm install -g vuepress

vuepress Entwicklung

Standardmäßig wird VuePress im Verzeichnis docs / ausgeführt und legt dort einen eigenen Ordner vuepress an. Nach der Eingabe der oben genannten Befehle startet es automatisch das Knotenpunkt Server und zeigt die Dokumentation auf localhost: 8080 / an. Hier ist ein Beispiel für die Dateistruktur.

Mit der richtigen Konfiguration wird VuePress eine vollständige und sehr ästhetische Seite erzeugen. Wie Sie auf dem Bildschirm oben sehen können, enthält unsere Dokumentation zwei benutzerdefinierte Komponenten - CodeHeading und ColorSample.

Ein einfacheres Beispiel für den Anfang wird CodeHeading sein.

CodeÜberschrift.vue

Vorlage:

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

Stile:

.code-überschrift {
 Breite: 100%;
 Höhe: 40px;
 Zeilenhöhe: 40px;
 Schriftgröße: 12px;
 Marge-unten: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 text-align: links;
 padding: 0 20px;
 box-sizing: border-box;
 Farbe: weiß;

 &__bad {
   Hintergrundfarbe: #cc0000;

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

 &__good {
   Hintergrundfarbe: #3eaf7c;

   &::after {
     content: "GUT";
   }
 }

 &__default {
   Hintergrundfarbe: #4e6e8e;
 }
}

Drehbuch:

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

Dies ist eine Standardsyntax für eine Vue.js-Komponente, die in Markdown-Dateien leicht verfügbar ist. Hier ist ein Beispiel für eine Implementierung (/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');

Auf diese Weise haben wir eine vollständig lesbare Lösung erhalten, um Beispiele für die Arbeit mit einem Code zu präsentieren.

Wahrscheinlich ist jeder Frontend-Entwickler schon einmal in die Situation gekommen, dass ihm die HEX-Darstellung einer beliebigen Farbe aus dem Grafikdesign fehlte. Und was wäre, wenn man immer eine Farbe zur Hand hätte und eine bestimmte Palette im Voraus festlegen könnte? Das ist richtig - die Dokumentation zwingt uns irgendwie dazu, uns an den Standard zu halten. Das Ergebnis könnte wie folgt aussehen:

In diesem Beispiel wurde die Komponente ColorPicker.vue verwendet. Sie dient nicht nur der Präsentation einer bestimmten Farbe - durch Anklicken eines Kreises kopieren wir automatisch den HEX-Code in die Zwischenablage.

Vorlage:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Zum Kopieren des HEX-Codes anklicken"
      >
        <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>(( Name ))</strong><br/>
        (( Farbe ))
      </p>
    </div>
  </div>
</template>

Stile:

.color-sample {
 Anzeige: inline-block;
 Breite: 45%;
 margin: 15px;

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

 &__circle {
   Breite: 70px;
   Höhe: 70px;
   float: links;
   Rand-Radius: 50%;
   Anzeige: flex;
   align-items: center;
   justify-Inhalt: zentriert;
   margin-right: 20px;
   Cursor: Zeiger;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   Position: relativ;
 }

 &__input {
   Schriftgröße: 12px;
   padding: 2px;
   Rand-Radius: 2px;
   border: 0;
   Anzeige: inline-block;
   Breite: 60px;
 }

 &__input-overlay {
   Position: absolut;
   top: 0;
   links: 0;
   rechts: 0;
   bottom: 0;
   Hintergrundfarbe: weiß;
   text-align: center;
 }
}

Drehbuch:

export default {
 props: {
   Farbe: String,
   name: String
 },
 berechnet: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 Methoden: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Ein Beispiel für eine Implementierung (/docs/Design/colors.md):

Es lohnt sich, auf die in VuePress eingebaute Suchmaschine zu achten:

Auf der Grundlage der Kopfzeilen in Markdown-Dateien funktioniert dies automatisch. Die auf diese Weise erstellte Konfiguration der Dokumentation sieht folgendermaßen aus:

module.exports = {
 Titel: 'Docs',
 themeConfig: {
   sidebar: [
     {
       Titel: 'Allgemein',
       zusammenklappbar: false,
       Kinder: [
         'Allgemein/Einführung.md',
         'Allgemein/Installation.md'
       ]
     },
     {
       Titel: 'Entwurf',
       zusammenklappbar: false,
       children: [
         'Design/Farben.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/Layout.md'
       ]
     },
     {
       Titel: 'Code',
       zusammenklappbar: false,
       children: [
         'Code/allgemein.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         'Code/git.md',
         'Code/deployment.md'
       ]
     }
   ],
   nav: [
     {
       text: 'Wissen',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs auf GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Mit dem vuepress bauen können wir im Handumdrehen statische HTML-Dateien generieren, die für eine schnelle Veröffentlichung mit vollständiger Unterstützung von Assets bereit sind.

Es ist erwähnenswert, dass VuePress eine automatische Bereitstellung auf verschiedenen Plattformen, einschließlich GitHub Pages, ermöglicht. Darüber hinaus macht die Möglichkeit, eigene Themes zu erstellen, VuePress zu einer sehr guten Blog-Lösung.

Wenn die obigen Beispiele Ihre Neugierde geweckt haben, empfehle ich Ihnen, sich mit der offiziellen Dokumentation von VuePress vertraut zu machen, um weitere Informationen zu erhalten Projekt.

Lesen Sie mehr:

• Optimierung des Codes mit Query Objects
• Vue.js Grundlagen-Tutorial. Wie beginnt man mit diesem Framework?
• Sicherheit in Javascript-Paketen
• GraphQL: Erfahrungen aus der Produktion