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

Εάν είστε εξοικειωμένοι με το Next.js, μπορείτε να το χρησιμοποιήσετε για να αναπτύξετε εύκολα έναν ιστότοπο τεκμηρίωσης. Το πλαίσιο Nextra φροντίζει για εσάς το νιφάδες. Το μόνο που έχετε να κάνετε είναι να προσθέσετε περιεχόμενο Markdown ή HTML και δεδομένα YAML ή JSON.

Ακολουθήστε αυτά τα βήματα για να δημιουργήσετε έναν ιστότοπο τεκμηρίωσης χρησιμοποιώντας το Nextra, ένα πρόγραμμα δημιουργίας στατικών τοποθεσιών που βασίζεται στο Next.js. Θα εγκαταστήσετε και θα ρυθμίσετε τις απαραίτητες εξαρτήσεις, στη συνέχεια θα μάθετε πώς να προσθέτετε νέα έγγραφα και σελίδες, να γράφετε Markdown και να συμπεριλαμβάνετε στοιχεία React.

Απαιτήσεις για τη δημιουργία τοποθεσίας εγγράφων με Nextra

Ξεκινήστε εγκαθιστώντας το Node.js αν δεν το έχετε κάνει ήδη. ο τελευταία έκδοση Node.js συνοδεύεται από το npm, τον διαχειριστή πακέτων κόμβου, τον οποίο θα χρειαστείτε για να εγκαταστήσετε εξαρτήσεις για αυτό το έργο.

instagram viewer

Εκτός από το Node.js, θα χρειαστεί να το εγκαταστήσετε Git. Χρειάζεστε το Git για να αναπτύξετε τον ιστότοπο σε σελίδες GitHub, Netlify ή σε άλλο πάροχο φιλοξενίας. Θα χρειαστείτε επίσης ένα προηγμένο πρόγραμμα επεξεργασίας κώδικα, όπως το VS Code.

Εγκατάσταση Nextra

Μπορείτε να χρησιμοποιήσετε α πρότυπο εγγράφων nextra για να εκκινήσετε έναν ιστότοπο τεκμηρίωσης. Εκκινήστε μια γραμμή εντολών και μεταβείτε στον κατάλογο στον οποίο θέλετε να ρυθμίσετε το έργο σας. Στη συνέχεια, εκτελέστε την ακόλουθη εντολή για να εκκινήσετε τον ιστότοπο τεκμηρίωσης:

git κλώνος https://github.com/shuding/nextra-docs-template

Αυτή η εντολή θα καλύψει μια εφαρμογή μέσα στον τρέχοντα κατάλογο. Στη συνέχεια, εκτελέστε την ακόλουθη εντολή για να εγκαταστήσετε τις εξαρτήσεις:

cd nextra-docs-template
npm εγκατάσταση

Μόλις ολοκληρωθεί η εγκατάσταση, ξεκινήστε την εφαρμογή. Κάντε το εκτελώντας την ακόλουθη εντολή στο τερματικό σας:

npm εκτέλεση dev

Αυτή η εντολή ξεκινά έναν διακομιστή ανάπτυξης στον localhost: 3000. Ακολουθήστε τον σύνδεσμο στο τερματικό σας για να δείτε τον ιστότοπο τεκμηρίωσης. Η αρχική σελίδα πρέπει να μοιάζει με αυτό:

Αν κοιτάξετε στην αριστερή πλευρά της σελίδας, θα βρείτε τις σελίδες με το όνομα Εισαγωγή και Μια άλλη σελίδα. Κάτω από αυτούς τους συνδέσμους σελίδας, θα βρείτε μια σελίδα με το όνομα Satori, φωλιασμένη μέσα στο Για προχωρημένους (Ένας φάκελος) Ευρετήριο. Τέλος, στην περιοχή πλοήγησης, θα βρείτε συνδέσμους προς το Σχετικά με και Επικοινωνία σελίδες.

Για να κατανοήσετε πώς λειτουργούν αυτές οι σελίδες, θα πρέπει πρώτα να καταλάβετε πώς το Next.js αποδίδει σελίδες.

Κατανόηση της δομής του καταλόγου

Εφόσον το Nextra χρησιμοποιεί το πλαίσιο Next.js, αποδίδει κάθε αρχείο στο σελίδες/ φάκελο ως ξεχωριστή σελίδα.

μεσα στην σελίδες κατάλογο, θα βρείτε τέσσερα αρχεία προτύπων: περίπου.mdx, προχωρημένος.mdx, άλλος.mdx, και ευρετήριο.mdx. Κάθε ένα από αυτά τα αρχεία αντιστοιχεί σε μια σελίδα στον ιστότοπο. για παράδειγμα, ευρετήριο.mdx αντιστοιχεί στην αρχική σελίδα. Το URL localhost: 3000/περίπου αντιστοιχεί στην περίπου.mdx, και ούτω καθεξής.

Μέσα σελίδες, υπάρχει επίσης ένας φάκελος με το όνομα προχωρημένος, που φιλοξενεί ένα μεμονωμένο αρχείο με το όνομα satori.mdx. Η διεύθυνση URL για αυτό το αρχείο θα είναι localhost: 3000/advanced/satori.

Παρατηρήστε πώς κάθε ένα από αυτά τα αρχεία τελειώνει με α .mdx επέκταση.

Τι είναι το MDX;

Εάν έχετε εμπειρία με το React, θα πρέπει να γνωρίζετε για το JSX. Αυτή είναι μια γλώσσα που μοιάζει με HTML που μπορείτε να χρησιμοποιήσετε για να περιγράψετε τη διεπαφή χρήστη των στοιχείων React.

Το MDX φορτώνει, αναλύει και αποδίδει το JSX σε ένα έγγραφο Markdown. Χάρη στο MDX, μπορείτε να γράψετε στοιχεία React και να τα εισαγάγετε στα έγγραφά σας Markdown όταν χρειάζεται. Τα αρχεία MDX τελειώνουν με την επέκταση .mdx και μπορούν να περιλαμβάνουν και Markdown και JSX.

Το MDX σάς επιτρέπει να συνδυάσετε τις γνώσεις σας για το Markdown με το React για να δημιουργήσετε επαναχρησιμοποιήσιμα στοιχεία. Μπορείς δημιουργία λειτουργικών μονάδων CSS για το στυλ των εξαρτημάτων. Αυτό σας βοηθά να οργανώσετε τα στοιχεία σας για να βελτιώσετε την αναγνωσιμότητα και τη συντηρησιμότητα.

Πώς να επεξεργαστείτε τις υπάρχουσες σελίδες στον ιστότοπο τεκμηρίωσης

Για να επεξεργαστείτε μια υπάρχουσα σελίδα, απλώς ανοίξτε το αντίστοιχο αρχείο και κάντε αλλαγές σε αυτό. Οι υποστηριζόμενες γλώσσες είναι η Markdown και η JSX.

Για παράδειγμα, ανοίξτε το ευρετήριο.mdx αρχείο και αντικαταστήστε το περιεχόμενο με αυτό:

# Καλώς ορίσατε στην τεκμηρίωσή μου
Χαίρομαι που σε βλέπω εδώ. Ευχαριστώ
## Τα Socials μου
Ακολουθησε με [Κελάδημα](https://twitter.com/kingchuuks) και [LinkedIn](https://linkedin.com/in/kingchuks)

Αυτό το παράδειγμα χρησιμοποιεί το Markdown για τη μορφοποίηση του περιεχομένου. Περιέχει μια επικεφαλίδα επιπέδου ένα, μια επικεφαλίδα επιπέδου δύο και δύο συνδέσμους μέσων κοινωνικής δικτύωσης.

Αποθηκεύστε το αρχείο και επισκεφτείτε την αρχική σελίδα της τοποθεσίας τεκμηρίωσής σας. Η σελίδα θα πρέπει τώρα να μοιάζει με αυτό:

Στο κάτω μέρος της σελίδας, μπορείτε επίσης να βρείτε την ημερομηνία τελευταίας ενημέρωσης του εγγράφου.

Προσθήκη νέας σελίδας

Προτού προσθέσετε μια νέα σελίδα, πρέπει πρώτα να αποφασίσετε εάν η σελίδα θα βρίσκεται στο σελίδες/ κατάλογο ή μέσα σε ένα φάκελο μέσα σε αυτόν. Χρησιμοποιήστε φακέλους εάν θέλετε να κατηγοριοποιήσετε τις σελίδες σας ή να αναπτύξετε μια ιεραρχία.

Σε αυτήν την περίπτωση, δημιουργήστε μια αυτόνομη σελίδα στο ανώτερο επίπεδο. Ανοίξτε ένα αρχείο με όνομα εγκατάσταση.mdx στον επεξεργαστή κώδικα και επικολλήστε τον ακόλουθο κώδικα Markdown σε αυτό:

# Οδηγός εγκατάστασης
Ακολουθήστε αυτόν τον οδηγό για να εγκαταστήσετε το πακέτο μου στο έργο σας
## 1. Εγκαταστήστε το Node.js
Για να εγκαταστήσετε το Node.js, επισκεφτείτε το
[Ιστότοπος τεκμηρίωσης Node.js](https://nodejs.org/en/download)

Αποθηκεύστε το αρχείο και ελέγξτε το πρόγραμμα περιήγησης. Θα βρείτε την ετικέτα εγκατάστασης στο πλαϊνό μενού. Όταν κάνετε κλικ στον σύνδεσμο, το περιεχόμενο του εγκατάσταση.mdx αποδίδει στη σελίδα:

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

Χρήση React Components

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

Μπορείτε να δείτε ένα παράδειγμα για το πώς μπορείτε να ενσωματώσετε στοιχεία στο Markdown στο άλλος.mdx αρχείο:

## Συστατικό
εισαγωγή {useState} από το 'react'
εισαγωγή στυλ από "../components/counters.module.css"
εξαγωγή const Μετρητής = () => { 
 const [count, setCount] = useState (0); 


 ΕΠΙΣΤΡΟΦΗ( 


 Κάντε κλικ {count} φορές


)
}

<Μετρητής />

## Εξωτερικά εξαρτήματα
εισαγωγή Μετρητών από "../components/counters"

<μετρητές />

Αυτό το αρχείο Markdown περιέχει έναν ορισμό για το στοιχείο Counter. Μετά από αυτό, εισάγει το στοιχείο Counters από το συστατικά Ευρετήριο.

Εάν πρόκειται να χρησιμοποιήσετε το ίδιο στοιχείο στον ιστότοπο τεκμηρίωσής σας, είναι καλύτερο να το δημιουργήσετε ως αυτόνομο στοιχείο και να το εισαγάγετε όταν το χρειάζεστε.

Μάθετε περισσότερα για το Markdown

Για να δημιουργήσετε περιεχόμενο για τον ιστότοπο τεκμηρίωσής σας, πρέπει να γνωρίζετε πώς να χρησιμοποιείτε το Markdown. Τα καλά νέα είναι ότι η σύνταξη Markdown είναι αρκετά εύκολο να εντοπιστεί. Όταν συνδυάζετε τις γνώσεις σας για το Markdown με το React, μπορείτε να δημιουργήσετε πραγματικά ισχυρούς ιστότοπους τεκμηρίωσης.