Η συγγραφή τεκμηρίωσης έγινε εύκολη χάρη στο VuePress

Ήταν πάντα ένα σημαντικό ζήτημα να καταβάλλεται η απαραίτητη προσπάθεια για το σχεδιασμό, τον προγραμματισμό και την υλοποίηση κάτι που να πληροί διάφορα κριτήρια:

• σας επιτρέπει να αποκτήσετε γρήγορα τη δομή μιας εφαρμογής
• σας επιτρέπει την ελεύθερη αναζήτηση στο περιεχόμενο
• παρέχει ένα σύνολο τεχνικών πληροφοριών σχετικά με τις χρησιμοποιούμενες λύσεις
• υποστηρίζει τη μορφοποίηση ενός κειμένου και ενός κωδικός
• μπορούν να αποθηκευτούν στο GitHub, κατά προτίμηση με δυνατότητα εύκολης ανάπτυξης.

Δεν είναι περίεργο που η τεκμηρίωση συνδέεται με μεγάλα έξοδα. Από την άλλη πλευρά, η ομάδα αυξάνεται, η εισαγωγή δημιουργεί πολλά έξοδα και γι' αυτό η υποστήριξη θέτει συνεχώς τις ίδιες ερωτήσεις στους προγραμματιστές. Κάποια στιγμή, όλοι λείπουν ... VuePress.

Το VuePress είναι μια γεννήτρια στατικών σελίδων βασισμένη στο Vue.js, το οποίο είναι ιδανικό για τη δημιουργία τεκμηρίωσης. Ένα καλό παράδειγμα αποτελεί η τεκμηρίωση του ίδιου του Vue.js.

Το VuePress σας επιτρέπει να επεξεργάζεστε κείμενα σε μορφή Markdown με τη χρήση των στοιχείων Vue, τα οποία, τελικά, παρέχουν ένα πραγματικά ευρύ φάσμα δυνατοτήτων. Ξεκινήστε απλώς με δύο εντολές:

npm install -g vuepress

vuepress dev

Από προεπιλογή, το VuePress εκτελείται στον κατάλογο docs / και δημιουργεί το δικό του φάκελο vuepress σε αυτόν. Μετά την εισαγωγή των παραπάνω εντολών, ξεκινάει αυτόματα το Κόμβος διακομιστή και εμφανίζει την τεκμηρίωση στη διεύθυνση localhost: 8080 /. Ακολουθεί ένα παράδειγμα της δομής του αρχείου.

Με την κατάλληλη διαμόρφωση, το VuePress θα δημιουργήσει μια πλήρη και πολύ αισθητική σελίδα. Όπως μπορείτε να δείτε στην παραπάνω οθόνη, η τεκμηρίωσή μας περιέχει δύο προσαρμοσμένα στοιχεία - CodeHeading και ColorSample.

Ένα απλούστερο παράδειγμα για την αρχή θα είναι το CodeHeading.

CodeHeading.vue

Πρότυπο:

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

Στυλ:

.code-heading {
 width: 100%,
 height: 40px,
 ύψος γραμμής: 40px,
 μέγεθος γραμματοσειράς: 12px,
 margin-bottom: -20px,
 border-top-left-radius: 6px,
 border-top-right-radius: 6px,
 text-align: left,
 padding: 0 20px,
 box-sizing: border-box,
 color: white,

 &__bad {
   background-color: #cc0000,

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

 &__good {
   background-color: #3eaf7c,

   &::after {
     content: "GOOD",
   }
 }

 &__default {
   background-color: #4e6e8e,
 }
}

Σενάριο:

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

Αυτή είναι μια τυπική σύνταξη ενός συστατικού Vue.js, η οποία είναι εύκολα διαθέσιμη σε αρχεία Markdown. Ακολουθεί ένα παράδειγμα υλοποίησης (/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'),

Με αυτόν τον τρόπο, λάβαμε μια απολύτως ευανάγνωστη λύση για την παρουσίαση παραδειγμάτων εργασίας με έναν κώδικα.

Πιθανώς κάθε προγραμματιστής frontend έχει βρεθεί σε μια κατάσταση όπου του έλειπε η αναπαράσταση HEX οποιουδήποτε χρώματος από το σχεδιασμό γραφικών. Και τι θα γινόταν αν μπορούσατε να έχετε πάντα το χρώμα στη διάθεσή σας και να καθορίζατε εκ των προτέρων μια συγκεκριμένη παλέτα; Ακριβώς - η τεκμηρίωση μας κάνει με κάποιο τρόπο να τηρούμε το πρότυπο. Το αποτέλεσμα μπορεί να μοιάζει με το ακόλουθο:

Σε αυτό το παράδειγμα, χρησιμοποιήθηκε το στοιχείο ColorPicker.vue. Εξυπηρετεί όχι μόνο την παρουσίαση ενός συγκεκριμένου χρώματος - κάνοντας κλικ σε έναν κύκλο, θα αντιγράψουμε αυτόματα τον κωδικό HEX στο πρόχειρο.

Πρότυπο:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Κάντε κλικ για να αντιγράψετε τον κωδικό HEX"
      >
        <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>(( όνομα ))</strong><br/>
        ((( color ))
      </p>
    </div>
  </div>
</template>

Στυλ:

.color-sample {
 display: inline-block,
 width: 45%,
 margin: 15px,

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

 &__circle {
   width: 70px,
   height: 70px,
   float: left,
   border-radius: 50%,
   display: flex,
   align-items: center,
   justify-content: center,
   margin-right: 20px,
   δρομέας: δείκτης,
   border: Tcfd4db: 1px solid #cfd4db,
 }

 &__input-wrapper {
   position: relative,
 }

 &__input {
   font-size: 12px,
   padding: 2px,
   border-radius: 2px,
   border: 0;
   εμφάνιση: inline-block,
   πλάτος: 60px,
 }

 &__input-overlay {
   position: absolute,
   top: 0;
   left: 0,
   right: 0,
   bottom: 0;
   χρώμα φόντου: λευκό,
   text-align: center,
 }
}

Σενάριο:

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

Ένα παράδειγμα εφαρμογής (/docs/Design/colors.md):

Αξίζει να δώσετε προσοχή στη μηχανή αναζήτησης που ενσωματώθηκε στο VuePress:

Με βάση τις επικεφαλίδες στα αρχεία Markdown λειτουργεί αυτόματα. Η διαμόρφωση της τεκμηρίωσης που γίνεται με αυτόν τον τρόπο έχει ως εξής:

module.exports = {
 title: 'Docs',
 themeConfig: {
   sidebar: [
     {
       title: 'General',
       collapsable: false,
       children: [
         'General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title: 'Design',
       collapsable: false,
       children: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title: 'Code',
       collapsable: false,
       children: [
         'Code/general.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         'Code/git.md',
         'Code/deployment.md'
       ]
     }
   ],
   nav: [
     {
       text: 'Γνώση',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Με το vuepress χτίσει εντολή, μπορούμε να δημιουργήσουμε άμεσα στατικά αρχεία HTML έτοιμα για γρήγορη δημοσίευση με πλήρη υποστήριξη περιουσιακών στοιχείων.

Αξίζει να αναφερθεί ότι το VuePress επιτρέπει την αυτόματη ανάπτυξη σε διάφορες πλατφόρμες, συμπεριλαμβανομένων των GitHub Pages. Επιπλέον, η δυνατότητα δημιουργίας των δικών σας θεμάτων καθιστά το VuePress μια αρκετά καλή λύση για ιστολόγια.

Αν τα παραπάνω παραδείγματα σας κίνησαν την περιέργεια, για περισσότερες πληροφορίες σας συνιστώ να γνωρίσετε την επίσημη τεκμηρίωση του VuePress έργο.

Διαβάστε περισσότερα:

• Βελτιστοποίηση κώδικα με αντικείμενα ερωτήσεων
• Vue.js βασικό σεμινάριο. Πώς να ξεκινήσετε με αυτό το πλαίσιο;
• Ασφάλεια σε πακέτα Javascript
• GraphQL: μαθήματα στην παραγωγή