Τα λάθη Markdown είναι φθηνότερα να διορθωθούν πριν εισέλθουν σε ένα αποθετήριο. Μόλις δεσμευτεί μια ενημέρωση README, μια καταχώριση αρχείου αλλαγών ή μια σημείωση εγγράφων, η συνομιλία αναθεώρησης συχνά μετατοπίζεται από το ίδιο το περιεχόμενο σε μικρά προβλήματα απόδοσης: χάλασε ένας πίνακας, ένα επίπεδο επικεφαλίδας μεταπήδησε, μια ετικέτα συνδέσμου είναι άδεια ή ένας φράκτης κώδικα έχασε τη γλώσσα του.
Μια προεπισκόπηση Markdown με γεύση GitHub σάς δίνει έναν γρήγορο έλεγχο πριν συμβεί αυτό. Δεν αντικαθιστά την τελική κριτική στο σύστημα προορισμού, αλλά συλλαμβάνει τα προβλήματα που είναι πιο εύκολο να χάσετε κατά τη γρήγορη σύνταξη. Το Markdown Validator της Converty συνδυάζει μια ζωντανή προεπισκόπηση με εστιασμένες προειδοποιήσεις για κοινά ζητήματα συγγραφής.
Γιατί το Markdown με γεύση GitHub χρειάζεται το δικό του πάσο προεπισκόπησης
Το Markdown με γεύση GitHub περιλαμβάνει πρακτική σύνταξη στην οποία βασίζονται πολλές τεχνικές ομάδες, συμπεριλαμβανομένων πινάκων, λιστών εργασιών, περιφράξεων κώδικα, συνδέσμων και ενσωματωμένου χειρισμού HTML. Ένα πρόγραμμα επεξεργασίας απλού κειμένου μπορεί να σας βοηθήσει να γράψετε το περιεχόμενο, αλλά μπορεί να μην δείχνει πώς θα αποδοθούν αυτά τα στοιχεία.
Αυτό έχει σημασία επειδή το οπτικό σχήμα ενός εγγράφου Markdown επηρεάζει την αναθεώρηση. Ένας πίνακας που φαίνεται στοιχισμένος στην πηγή μπορεί να εξακολουθεί να αποδίδεται κακώς. Μια ιεραρχία επικεφαλίδων που φαίνεται προφανής κατά τη γραφή μπορεί να γίνει μπερδεμένη μετά τη μετατροπή. Ένας φράκτης κώδικα χωρίς ετικέτα γλώσσας μπορεί να κάνει πιο δύσκολη τη σάρωση των παραδειγμάτων.
Το πάσο προεπισκόπησης δεν αφορά τη στίλβωση κάθε πρότασης. Πρόκειται για τη διασφάλιση ότι το έγγραφο συμπεριφέρεται σαν μια αναγνώσιμη σελίδα Markdown πριν φτάσει στην επόμενη ροή εργασίας.
Μια πρακτική ροή εργασίας Markdown πριν από τη δέσμευση
Χρησιμοποιήστε την προεπισκόπηση του προγράμματος περιήγησης ενώ το έγγραφο εξακολουθεί να είναι εύκολο να αλλάξει.
- Ανοίξτε το Markdown Validator.
- Επικολλήστε την ενότητα README, την ενημέρωση εγγράφων, την καταχώριση αλλαγών ή τη σημείωση έκδοσης.
- Ελέγξτε την προεπισκόπηση που έχει αποδοθεί για εκπλήξεις διάταξης.
- Διαβάστε τη λίστα προειδοποιήσεων για άλματα κατεύθυνσης, διπλή χρήση H1, εναλλακτικό κείμενο εικόνας που λείπει, κενούς συνδέσμους και περιφράξεις κώδικα χωρίς ετικέτα.
- Διορθώστε το έγγραφο προέλευσης πριν το δεσμεύσετε ή το επικολλήσετε στο τελικό σύστημα.
Αυτή η ροή εργασίας είναι σκόπιμα σύντομη. Δεν μετακινείτε έγγραφα σε μια νέα πλατφόρμα συγγραφής. Δίνετε το Markdown one focused inspection pass πριν το αποθετήριο γίνει η επιφάνεια ελέγχου.
Τι μπορεί να πιάσει νωρίς η προεπισκόπηση
Μια χρήσιμη προεπισκόπηση Markdown θα βοηθήσει με τα λάθη που επιβραδύνουν τις κριτικές:
- πίνακες που δεν διαβάζονται καθαρά
- επικεφαλίδες που παρακάμπτουν επίπεδα
- πολλαπλές επικεφαλίδες H1 σε ένα έγγραφο
- σύνδεσμοι χωρίς χρήσιμες ετικέτες
- εικόνες χωρίς εναλλακτικό κείμενο
- φράχτες κωδικών χωρίς ετικέτες γλώσσας
- ακατέργαστο HTML που πρέπει να αντιμετωπίζεται προσεκτικά
Αυτοί οι έλεγχοι είναι ιδιαίτερα χρήσιμοι για τεχνικό περιεχόμενο, επειδή τα μικρά ζητήματα δομής μπορεί να κάνουν τα παραδείγματα πιο δύσκολο να εμπιστευθούν.
Όταν η προεπισκόπηση του προγράμματος περιήγησης δεν είναι αρκετή
Η προεπισκόπηση του προγράμματος περιήγησης είναι ένας πρώιμος έλεγχος και όχι η τελική πηγή αλήθειας για κάθε πλατφόρμα εγγράφων. Εάν ο τελικός προορισμός σας χρησιμοποιεί προσαρμοσμένα στοιχεία, ειδικές επεκτάσεις Markdown ή απόδοση για συγκεκριμένο προϊόν, θα πρέπει να ελέγξετε τη σελίδα σε αυτό το περιβάλλον.
Αυτό το όριο είναι σημαντικό. Η μετατροπή είναι χρήσιμη πριν αναλάβει το βαρύτερο σύστημα. Δίνει σε συγγραφείς, προγραμματιστές και αναθεωρητές έναν γρήγορο τρόπο να εντοπίζουν συνηθισμένα ζητήματα Markdown χωρίς να περιμένουν την έκδοση εγγράφων ή την αναθεώρηση αιτήματος έλξης.
Για ευρύτερη καθοδήγηση σχετικά με την ποιότητα του περιεχομένου, διαβάστε το How to Catch Markdown Issues Before Publishing. Για μεταβιβάσεις ομάδων, συνεχίστε με το Πώς οι ομάδες προϊόντων και εγγράφων μπορούν να αξιολογήσουν το Markdown Without Losing Formatting.
Ανοίξτε το Markdown Validator πριν πραγματοποιήσετε Markdown όταν θέλετε η προεπισκόπηση και οι προειδοποιήσεις σε ένα μέρος.
