Nextra vă permite să construiți un site în câteva minute, deci este perfect pentru distribuirea de documente echipei dvs.

Dacă sunteți familiarizat cu Next.js, îl puteți utiliza pentru a dezvolta cu ușurință un site de documentare. Cadrul Nextra are grija de problemele pentru tine; tot ce trebuie să faceți este să adăugați conținut Markdown sau HTML și date YAML sau JSON.

Parcurgeți acești pași pentru a crea un site de documentare folosind Nextra, un generator de site static bazat pe Next.js. Veți instala și configura dependențele necesare, apoi veți afla cum să adăugați documente și pagini noi, să scrieți Markdown și să includeți componentele React.

Cerințe pentru construirea unui site de documente cu Nextra

Începeți prin a instala Node.js dacă nu ați făcut-o deja. The cea mai recentă versiune Node.js vine cu npm, managerul de pachete nod, de care veți avea nevoie pentru a instala dependențe pentru acest proiect.

Pe lângă Node.js, va trebui să instalați Git. Aveți nevoie de Git pentru a implementa site-ul pe paginile GitHub, Netlify sau alt furnizor de găzduire. De asemenea, veți avea nevoie de un editor de cod avansat, cum ar fi VS Code.

instagram viewer

Instalarea Nextra

Puteți folosi a șablon de documente nextra pentru a porni un site de documentare. Lansați un prompt de comandă și navigați la directorul în care doriți să configurați proiectul. Apoi rulați următoarea comandă pentru a porni site-ul de documentație:

clona git https://github.com/shuding/nextra-docs-template

Această comandă va schelă o aplicație în directorul curent. Apoi, rulați următoarea comandă pentru a instala dependențele:

cd nextra-docs-template
instalare npm

După finalizarea instalării, porniți aplicația. Faceți acest lucru rulând următoarea comandă pe terminalul dvs.:

npm run dev

Această comandă pornește un server de dezvoltare la localhost: 3000. Urmați linkul de pe terminalul dvs. pentru a vizualiza site-ul de documentare. Pagina principală ar trebui să arate astfel:

Dacă te uiți în partea stângă a paginii, vei găsi paginile numite Introducere și O altă pagină. Sub aceste link-uri de pagină, veți găsi o pagină numită Satori, imbricată în interiorul Avansat (A folder) director. În cele din urmă, în zona de navigare, veți găsi link-uri către Despre și a lua legatura pagini.

Pentru a înțelege cum funcționează aceste pagini, va trebui mai întâi să înțelegeți cum redă paginile Next.js.

Înțelegerea structurii directorului

Deoarece Nextra folosește cadrul Next.js, redă fiecare fișier din fișierul pagini/ folder ca o pagină separată.

În interiorul pagini director, veți găsi patru fișiere șablon: despre.mdx, avansat.mdx, altul.mdx, și index.mdx. Fiecare dintre aceste fișiere corespunde unei pagini de pe site; de exemplu, index.mdx corespunde paginii de start. URL-ul localhost: 3000/aproximativ corespunde despre.mdx, și așa mai departe.

Interior pagini, există și un folder numit avansat, adăpostind un singur fișier numit satori.mdx. URL-ul pentru acest fișier va fi localhost: 3000/advanced/satori.

Observați cum fiecare dintre aceste fișiere se termină cu a .mdx extensie.

Ce este MDX?

Daca ai experiență cu React, ar trebui să știți despre JSX. Acesta este un limbaj asemănător HTML pe care îl puteți folosi pentru a descrie interfața de utilizare a componentelor React.

MDX încarcă, analizează și redă JSX într-un document Markdown. Datorită MDX, puteți scrie componente React și le puteți importa în documentele dvs. Markdown atunci când este necesar. Fișierele MDX se termină cu extensia .mdx și pot include atât Markdown, cât și JSX.

MDX vă permite să vă combinați cunoștințele despre Markdown cu React pentru a crea componente reutilizabile. Puteți creați module CSS pentru a stila componentele. Acest lucru vă ajută să vă organizați componentele pentru a îmbunătăți lizibilitatea și mentenabilitatea.

Cum să editați paginile existente pe site-ul de documentare

Pentru a edita o pagină existentă, pur și simplu deschideți fișierul corespunzător și faceți-i modificări. Limbile acceptate sunt Markdown și JSX.

De exemplu, deschideți index.mdx fișier și înlocuiți conținutul cu acesta:

# Bun venit la documentația mea
Mă bucur să te văd aici. Mulțumiri
## Rețelele mele sociale
Urmărește-mă pe [Stare de nervozitate](https://twitter.com/kingchuuks) și [LinkedIn](https://linkedin.com/in/kingchuks)

Acest exemplu folosește Markdown pentru a formata conținutul. Conține un titlu de nivel unu, un titlu de nivel doi și două link-uri de socializare.

Salvați fișierul și vizitați pagina de pornire a site-ului dvs. de documentare. Pagina ar trebui să arate acum astfel:

În partea de jos a paginii, puteți găsi și data ultimei actualizări a documentului.

Adăugarea unei pagini noi

Înainte de a adăuga o nouă pagină, trebuie mai întâi să decideți dacă pagina va fi în pagini/ director sau în interiorul unui folder din acesta. Folosiți foldere dacă doriți să vă clasificați paginile sau să dezvoltați o ierarhie.

În acest caz, creați o pagină autonomă la nivelul superior. Deschideți un fișier numit instalare.mdx în editorul de cod și inserați următorul cod Markdown în el:

# Ghid de instalare
Urmați acest ghid pentru a instala pachetul meu în proiectul dvs
## 1. Instalați Node.js
Pentru a instala Node.js, vizitați
[Site-ul de documentare Node.js](https://nodejs.org/en/download)

Salvați fișierul și verificați browserul. Veți găsi eticheta de instalare în meniul lateral. Când faceți clic pe link, conținutul instalare.mdx randeaza pe pagina:

Puteți schimba eticheta și efectua alte configurații în fișierul _meta.json din directorul de pagini. Pentru a afla mai multe despre acest lucru, consultați Organizați fișierele sectiune de documentația Nextra.

Utilizarea componentelor React

Fișierele MDX pot include JSX, care este limbajul folosit de React. Puteți crea o componentă în folderul componente și o puteți importa în oricare dintre documentele de pe site-ul dvs.

Puteți vedea un exemplu despre cum puteți încorpora componente în Markdown în altul.mdx fişier:

## Componentă
import {useState} din „react”
importați stiluri din „../components/counters.module.css”
export const Counter = () => { 
 const [count, setCount] = useState (0); 


 întoarcere( 


 S-a făcut clic de {count} ori


)
}

<Tejghea />

## Componente externe
importa contoare din „../components/counters”

<Contoare />

Acest fișier Markdown conține o definiție pentru componenta Counter. După aceea, importă componenta Counters din componente director.

Dacă veți folosi aceeași componentă pe site-ul dvs. de documentare, cel mai bine este să o creați ca componentă autonomă și să o importați când aveți nevoie.

Aflați mai multe despre Markdown

Pentru a crea conținut pentru site-ul de documentare, trebuie să știți cum să utilizați Markdown. Vestea bună este că sintaxa Markdown este destul de ușor de preluat. Atunci când vă combinați cunoștințele despre Markdown cu React, puteți crea site-uri de documentare cu adevărat solide.