Ζωντανές οδηγίες - MDX και άλλα πλαίσια

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

Εάν χρειάζεται να γράψετε μεγάλο κείμενο, το Markdown είναι μια εξαιρετική εναλλακτική λύση στην HTML. Μερικές φορές η σύνταξη Markdown δεν είναι αρκετή. Σε αυτή την περίπτωση μπορούμε να χρησιμοποιήσουμε HTML μέσα σε αυτό. Για παράδειγμα, προσαρμοσμένα στοιχεία. Επομένως, εάν δημιουργείτε ένα σύστημα σχεδίασης με εγγενή στοιχεία ιστού, μπορούν εύκολα να συμπεριληφθούν στην τεκμηρίωση κειμένου. Εάν χρησιμοποιείτε το React (ή οποιοδήποτε άλλο πλαίσιο JSX, όπως το Preact ή το Vue), μπορείτε να κάνετε το ίδιο πράγμα χρησιμοποιώντας το MDX.

Αυτό το άρθρο είναι μια ευρεία επισκόπηση των εργαλείων για τη σύνταξη τεκμηρίωσης και τη δημιουργία οδηγιών. Δεν χρησιμοποιούν όλα τα εργαλεία που αναφέρονται εδώ το MDX, αλλά περιλαμβάνεται όλο και περισσότερο στα εργαλεία τεκμηρίωσης.

Τι είναι το MDX;

αρχείο .mdx έχει την ίδια σύνταξη με το Markdown, αλλά σας επιτρέπει να εισάγετε διαδραστικά στοιχεία JSX και να τα ενσωματώνετε στο περιεχόμενό σας. Η υποστήριξη για τα στοιχεία Vue είναι σε alpha. Για να ξεκινήσετε να εργάζεστε με το MDX, απλώς εγκαταστήστε το "Create React App". Υπάρχουν πρόσθετα για Next.js και Gatsby. Η επόμενη έκδοση του Docusaurus (έκδοση 2) ​​θα έχει επίσης εγγενή υποστήριξη.

Συγγραφή τεκμηρίωσης με το Docusaurus

Ο Docusaurus έγραψε στο Facebook. Το χρησιμοποιούν σε κάθε έργο ανοιχτού κώδικα εκτός από το React. Εκτός εταιρείας χρησιμοποιείται από Redux, Prettier, Gulp και Babel.

Έργα που χρησιμοποιούν το Docusaurus.

Το Docusaurus μπορεί να χρησιμοποιηθεί για τη γραφή κάθε τεκμηρίωση, όχι μόνο για την περιγραφή του frontend. Διαθέτει React κάτω από την κουκούλα, αλλά δεν χρειάζεται να το γνωρίζετε για να το χρησιμοποιήσετε. Χρειάζονται τα αρχεία Markdown σας, είναι έτοιμη μια μικρή ποσότητα μαγικής και καλά δομημένη, μορφοποιημένη και ευανάγνωστη τεκμηρίωση με όμορφο σχεδιασμό.

Στον ιστότοπο του Redux μπορείτε να δείτε το τυπικό πρότυπο Docusaurus

Οι ιστότοποι που έχουν κατασκευαστεί με το Docusaurus μπορούν επίσης να περιλαμβάνουν ένα ιστολόγιο που βασίζεται σε Markdown. Το Prism.js συνδέεται αμέσως για επισήμανση σύνταξης. Παρά το γεγονός ότι το Docusaurus εμφανίστηκε σχετικά πρόσφατα, αναγνωρίστηκε ως το καλύτερο εργαλείο του 2018 στο StackShare.

Άλλες επιλογές δημιουργίας περιεχομένου

Το Docusaurus έχει σχεδιαστεί ειδικά για τη δημιουργία τεκμηρίωσης. Φυσικά, υπάρχουν ένα εκατομμύριο και ένας τρόποι για να δημιουργήσετε έναν ιστότοπο - μπορείτε να αναπτύξετε τη δική σας λύση σε οποιαδήποτε γλώσσα, CMS ή να χρησιμοποιήσετε μια δημιουργία στατικής τοποθεσίας.

Για παράδειγμα, η τεκμηρίωση για το React, το σύστημα σχεδίασης IBM, το Apollo και το Ghost CMS χρησιμοποιούν το Gatsby - μια δημιουργία στατικών τοποθεσιών που χρησιμοποιείται συχνά για ιστολόγια. Εάν εργάζεστε με το Vue, τότε το VuePress είναι μια καλή επιλογή για εσάς. Μια άλλη επιλογή είναι να χρησιμοποιήσετε μια γεννήτρια γραμμένη σε Python - MkDocs. Είναι ανοιχτού κώδικα και έχει ρυθμιστεί χρησιμοποιώντας ένα μόνο αρχείο YAML. Το GitBook είναι επίσης μια καλή επιλογή, αλλά είναι δωρεάν μόνο για δημόσιες και μη εμπορικές ομάδες. Μπορείτε επίσης απλά να ανεβάσετε αρχεία mardown χρησιμοποιώντας το Git και να εργαστείτε μαζί τους στο Github.

Στοιχεία τεκμηρίωσης: Docz, Storybook και Styleguidist

Οδηγίες, σχεδιασμός συστήματος, βιβλιοθήκες στοιχείων - όπως και να τις ονομάσετε, έχει γίνει πολύ δημοφιλές τον τελευταίο καιρό. Η εμφάνιση πλαισίων στοιχείων όπως το React και τα εργαλεία που αναφέρονται εδώ τα έχουν μετατρέψει από έργα ματαιοδοξίας σε χρήσιμα εργαλεία.

Το Storybook, το Docz και το Styleguidist κάνουν όλοι το ίδιο πράγμα: εμφανίζουν διαδραστικά στοιχεία και τεκμηριώνουν το API τους. Ένα έργο μπορεί να έχει δεκάδες ή και εκατοντάδες στοιχεία - όλα με διαφορετικές καταστάσεις και στυλ. Εάν θέλετε τα εξαρτήματα να επαναχρησιμοποιηθούν, οι άνθρωποι πρέπει να γνωρίζουν ότι υπάρχουν. Για να το κάνετε αυτό, απλώς καταγράψτε τα εξαρτήματα. Οι οδηγίες παρέχουν μια εύκολη επισκόπηση όλων των στοιχείων σας. Αυτό βοηθά στη διατήρηση της οπτικής συνέπειας και στην αποφυγή επαναλαμβανόμενων εργασιών.

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

Μαζί με μια οπτική επίδειξη διάφορων καταστάσεων και μια λίστα ιδιοτήτων, είναι συχνά απαραίτητο να γραφτεί μια γενική περιγραφή του περιεχομένου - σκεπτικά σχεδιασμού, περιπτώσεις χρήσης ή περιγραφές των αποτελεσμάτων δοκιμών χρήστη. Το Markdown είναι πολύ εύκολο στην εκμάθηση - ιδανικά, οι οδηγίες θα πρέπει να είναι ένας κοινός πόρος για σχεδιαστές και προγραμματιστές. Το Docz, το Styleguidist και το Storybook προσφέρουν έναν τρόπο εύκολης ανάμειξης του Markdown με εξαρτήματα.

Docz

Προς το παρόν, το Docz λειτουργεί μόνο με το React, αλλά βρίσκεται σε εξέλιξη ενεργή εργασία για την υποστήριξη στοιχείων Preact, Vue και web. Το Docz είναι το πιο πρόσφατο από τα τρία εργαλεία, αλλά έχει καταφέρει να συγκεντρώσει πάνω από 14 αστέρια στο Github. Το Docz εισάγει δύο στοιχεία − <Playground> и < Props >. Εισάγονται και χρησιμοποιούνται σε αρχεία .mdx.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

Μπορείτε να τυλίξετε τα δικά σας στοιχεία React <Playground>για να δημιουργήσετε ένα ανάλογο του ενσωματωμένου CodePen ή CodeSandbox - δηλαδή, βλέπετε το στοιχείο σας και μπορείτε να το επεξεργαστείτε.

<Playground>
  <Button>click</Button>
</Playground>

<Props> θα εμφανίσει όλες τις διαθέσιμες ιδιότητες για ένα δεδομένο στοιχείο React, τις προεπιλεγμένες τιμές και εάν η ιδιότητα απαιτείται.

<Props of={Button} />

Προσωπικά, θεωρώ ότι αυτή η προσέγγιση που βασίζεται στο MDX είναι η πιο εύκολη στην κατανόηση και η πιο εύκολη στην εργασία.

Εάν είστε λάτρης της δημιουργίας στατικών τοποθεσιών Gatsby, το Docz προσφέρει μια εξαιρετική ενσωμάτωση.

Οδηγός στυλ

Όπως και το Docz, τα παραδείγματα γράφονται χρησιμοποιώντας τη σύνταξη Markdown. Το Styleguidist χρησιμοποιεί μπλοκ κώδικα Markdown (τριπλά εισαγωγικά) σε κανονικά αρχεία .md αρχεία, όχι MDX.

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

Τα μπλοκ κώδικα στο Markdown συνήθως εμφανίζουν απλώς κώδικα. Όταν χρησιμοποιείτε το Styleguidist, οποιοδήποτε μπλοκ κώδικα με ετικέτα γλώσσας js, jsx ή javascript θα αποδοθεί ως στοιχείο React. Όπως και το Docz, ο κώδικας είναι επεξεργάσιμος - μπορείτε να αλλάξετε ιδιότητες και να δείτε αμέσως το αποτέλεσμα.

Το Styleguidist θα δημιουργήσει αυτόματα έναν πίνακα ιδιοτήτων από δηλώσεις PropTypes, Flow ή Typescript.

Το Styleguidist υποστηρίζει αυτήν τη στιγμή το React και το Vue.

Βιβλίο ιστοριών

Το Storybook τοποθετείται ως "περιβάλλον ανάπτυξης στοιχείων UI". Αντί να γράφετε παραδείγματα στοιχείων μέσα σε αρχεία Markdown ή MDX, γράφετε ιστορία μέσα σε αρχεία Javascript. Ιστορία τεκμηριώστε τη συγκεκριμένη κατάσταση ενός στοιχείου. Για παράδειγμα, ένα στοιχείο μπορεί να έχει ιστορικά για μια κατάσταση φόρτωσης και μια κατάσταση απενεργοποιημένη (ανάπηρος).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Το Storybook είναι πολύ πιο περίπλοκο από το Styleguidist και το Docz. Αλλά ταυτόχρονα, αυτή είναι η πιο δημοφιλής επιλογή· το έργο έχει περισσότερα από 36 αστέρια στο Github. Είναι ένα έργο ανοιχτού κώδικα με 000 συντελεστές και προσωπικό πλήρους απασχόλησης. Χρησιμοποιείται από τις Airbnb, Algolia, Atlassian, Lyft και Salesforce. Το Storybook υποστηρίζει περισσότερα πλαίσια από τους ανταγωνιστές - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte και κανονικό HTML.

Σε μελλοντική κυκλοφορία θα υπάρξουν δυνατότητες από το Docz και θα παρουσιαστεί το MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Οι νέες δυνατότητες του Storybook θα κυκλοφορήσουν σταδιακά τους επόμενους μήνες και φαίνεται ότι θα είναι ένα μεγάλο βήμα προς τα εμπρός.

Αποτελέσματα της

Τα οφέλη μιας βιβλιοθήκης προτύπων εκθειάζονται σε εκατομμύρια άρθρα στο Medium. Όταν γίνονται καλά, διευκολύνουν τη δημιουργία σχετικών προϊόντων και τη διατήρηση της ταυτότητας. Φυσικά, κανένα από αυτά τα εργαλεία δεν θα δημιουργήσει ως δια μαγείας ένα σύστημα σχεδίασης. Αυτό απαιτεί προσεκτικό σχεδιασμό και CSS. Αλλά όταν έρθει η ώρα να κάνετε ένα σύστημα σχεδίασης προσβάσιμο σε ολόκληρη την εταιρεία, το Docz, το Storybook και το Styleguidist είναι εξαιρετικές επιλογές.

Από τον μεταφραστή. Αυτή είναι η πρώτη μου εμπειρία στο Habré. Αν βρείτε ανακρίβειες, ή έχετε προτάσεις για τη βελτίωση του άρθρου, γράψτε μου σε προσωπικό μήνυμα.

Πηγή: www.habr.com