Izgradite Doc stranicu s Next.js koristeći Nextru

Ako ste upoznati s Next.js, možete ga koristiti za razvoj dokumentacijske stranice s lakoćom. Okvir Nextra brine se o sitnicama umjesto vas; sve što trebate učiniti je dodati Markdown ili HTML sadržaj i YAML ili JSON podatke.

Prođite kroz ove korake za izradu stranice s dokumentacijom pomoću Nextre, generatora statičkih stranica temeljenog na Next.js. Instalirat ćete i postaviti potrebne ovisnosti, zatim naučiti kako dodati nove dokumente i stranice, napisati Markdown i uključiti React komponente.

Zahtjevi za izgradnju Doc stranice s Nextrom

Započnite instaliranjem Node.js ako to već niste učinili. The najnovija verzija Node.js dolazi s npm-om, upraviteljem paketa čvora, koji će vam trebati za instaliranje ovisnosti za ovaj projekt.

Osim Node.js, morat ćete instalirati Git. Potreban vam je Git za implementaciju stranice na GitHub stranice, Netlify ili drugog pružatelja usluge hostinga. Trebat će vam i napredni uređivač koda, kao što je VS Code.

Instaliranje Nextre

Možete koristiti a nextra docs predložak za pokretanje stranice s dokumentacijom. Pokrenite naredbeni redak i dođite do direktorija u kojem želite postaviti svoj projekt. Zatim pokrenite sljedeću naredbu za pokretanje stranice s dokumentacijom:

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

Ova naredba će postaviti aplikaciju unutar trenutnog direktorija. Zatim pokrenite sljedeću naredbu da biste instalirali ovisnosti:

predložak cd nextra-docs
npm instalirati

Kada instalacija završi, pokrenite aplikaciju. Učinite to pokretanjem sljedeće naredbe na svom terminalu:

npm run dev

Ova naredba pokreće razvojni poslužitelj na lokalnom hostu: 3000. Slijedite vezu na svom terminalu da biste vidjeli dokumentaciju. Početna stranica bi trebala izgledati ovako:

Ako pogledate lijevu stranu stranice, pronaći ćete navedene stranice Uvod i Još jedna stranica. Ispod ovih poveznica stranica, pronaći ćete stranicu pod nazivom Satori, ugniježđenu unutar Napredno (Mapa) imenik. Konačno, u navigacijskom području pronaći ćete poveznice na Oko i Kontakt stranice.

Da biste razumjeli kako ove stranice funkcioniraju, prvo morate razumjeti kako Next.js prikazuje stranice.

Razumijevanje strukture imenika

Budući da Nextra koristi okvir Next.js, renderira svaku datoteku u stranice/ mapu kao zasebnu stranicu.

Unutar stranice direktoriju, pronaći ćete četiri datoteke predložaka: oko.mdx, napredni.mdx, drugi.mdx, i indeks.mdx. Svaka od ovih datoteka odgovara stranici na web stranici; na primjer, indeks.mdx odgovara početnoj stranici. URL lokalni host: 3000/otprilike odgovara oko.mdx, i tako dalje.

Iznutra stranice, tu je i mapa pod nazivom Napredna, koja sadrži jednu datoteku pod nazivom satori.mdx. URL za ovu datoteku bit će lokalni host: 3000/napredno/satori.

Primijetite kako svaka od ovih datoteka završava s a .mdx proširenje.

Što je MDX?

Ako imate iskustva s Reactom, trebali biste znati o JSX-u. Ovo je jezik sličan HTML-u koji možete koristiti za opisivanje korisničkog sučelja komponenti Reacta.

MDX učitava, analizira i prikazuje JSX u Markdown dokumentu. Zahvaljujući MDX-u, možete pisati React komponente i uvoziti ih u svoje Markdown dokumente kada je to potrebno. MDX datoteke završavaju ekstenzijom .mdx i mogu uključivati ​​Markdown i JSX.

MDX vam omogućuje da kombinirate svoje znanje o Markdownu s Reactom za stvaranje komponenti za višekratnu upotrebu. Možeš kreirati CSS module stilizirati komponente. To vam pomaže da organizirate svoje komponente kako biste poboljšali čitljivost i lakoću održavanja.

Kako urediti postojeće stranice na dokumentacijskom mjestu

Kako biste uredili postojeću stranicu, jednostavno otvorite odgovarajuću datoteku i unesite izmjene u nju. Podržani jezici su Markdown i JSX.

Na primjer, otvorite indeks.mdx datoteku i zamijenite sadržaj ovim:

# Dobro došli u moju dokumentaciju
Drago mi je što te vidim ovdje. Hvala
## Moje društvene mreže
Prati me na [Cvrkut](https://twitter.com/kingchuuks) i [LinkedIn](https://linkedin.com/in/kingchuks)

Ovaj primjer koristi Markdown za oblikovanje sadržaja. Sadrži naslov prve razine, naslov druge razine i dvije veze na društvene mreže.

Spremite datoteku i posjetite početnu stranicu svoje dokumentacijske stranice. Stranica bi sada trebala izgledati ovako:

Na dnu stranice također možete pronaći datum posljednjeg ažuriranja dokumenta.

Dodavanje nove stranice

Prije dodavanja nove stranice prvo morate odlučiti hoće li stranica biti u stranice/ imenik ili unutar mape unutar njega. Koristite mape ako želite kategorizirati svoje stranice ili razviti hijerarhiju.

U tom slučaju izradite samostalnu stranicu na najvišoj razini. Otvorite datoteku pod nazivom instalacija.mdx u svoj uređivač koda i u njega zalijepite sljedeći Markdown kod:

# Vodič za instalaciju
Slijedite ovaj vodič da biste instalirali moj paket u svoj projekt
## 1. Instalirajte Node.js
Da biste instalirali Node.js, posjetite
[Stranica s dokumentacijom za Node.js](https://nodejs.org/en/download)

Spremite datoteku i provjerite preglednik. U bočnom izborniku pronaći ćete oznaku Instalacija. Kada kliknete na poveznicu, sadržaj instalacija.mdx prikazuje na stranici:

Možete promijeniti oznaku i izvršiti druge konfiguracije u datoteci _meta.json unutar direktorija stranica. Da biste saznali više o ovome, pogledajte Organizirajte datoteke odjeljak od Nextrina dokumentacija.

Korištenje React komponenti

MDX datoteke mogu uključivati ​​JSX, jezik koji React koristi. Možete izraditi komponentu unutar mape komponenti i uvesti je u bilo koji dokument na vašem web-mjestu.

Možete vidjeti primjer kako možete ugraditi komponente u Markdown u drugi.mdx datoteka:

## Komponenta
uvoz {useState} iz 'react'
uvoz stilova iz '../components/counters.module.css'
izvoz const Brojač = () => { 
 const [count, setCount] = useState (0); 
 povratak( 

 setCount (count+1)} className={styles.counter}> 
 Kliknuto {count} puta