Nextra vam omogoča, da ustvarite spletno mesto v nekaj minutah, zato je kot nalašč za distribucijo dokumentov vaši ekipi.

Če poznate Next.js, ga lahko uporabite za enostavno razvijanje spletnega mesta z dokumentacijo. Ogrodje Nextra namesto vas poskrbi za malenkosti; vse kar morate storiti je, da dodate vsebino Markdown ali HTML in podatke YAML ali JSON.

Sprehodite se skozi te korake za izdelavo spletnega mesta z dokumentacijo z uporabo Nextra, generatorja statičnih spletnih mest, ki temelji na Next.js. Namestili in nastavili boste potrebne odvisnosti, nato pa se naučili, kako dodati nove dokumente in strani, napisati Markdown in vključiti komponente React.

Zahteve za izdelavo spletnega mesta Doc z Nextro

Začnite z namestitvijo Node.js, če tega še niste storili. The najnovejšo različico Node.js prihaja z npm, upravljalnikom paketov vozlišča, ki ga boste potrebovali za namestitev odvisnosti za ta projekt.

Poleg Node.js boste morali namestiti Git. Git potrebujete za uvedbo mesta na strani GitHub, Netlify ali drugega ponudnika gostovanja. Potrebovali boste tudi napredni urejevalnik kode, kot je VS Code.

Namestitev Nextre

Uporabite lahko a predloga dokumentov nextra za zagon mesta z dokumentacijo. Zaženite ukazni poziv in se pomaknite do imenika, v katerem želite nastaviti svoj projekt. Nato zaženite naslednji ukaz za zagon mesta z dokumentacijo:

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

Ta ukaz bo postavil aplikacijo znotraj trenutnega imenika. Nato zaženite naslednji ukaz za namestitev odvisnosti:

cd nextra-docs-template
namestitev npm

Ko je namestitev končana, zaženite aplikacijo. To storite tako, da na svojem terminalu zaženete naslednji ukaz:

npm run dev

Ta ukaz zažene razvojni strežnik na localhost: 3000. Za ogled spletnega mesta z dokumentacijo sledite povezavi na svojem terminalu. Domača stran bi morala izgledati takole:

Če pogledate na levo stran strani, boste našli poimenovane strani Uvod in Druga stran. Pod temi povezavami strani boste našli stran z imenom Satori, ki je ugnezdena znotraj Napredno (mapa) imenik. Nazadnje boste v navigacijskem območju našli povezave do O tem in Kontakt strani.

Če želite razumeti, kako te strani delujejo, morate najprej razumeti kako Next.js upodablja strani.

Razumevanje strukture imenika

Ker Nextra uporablja ogrodje Next.js, vsako datoteko upodobi v strani/ mapo kot ločeno stran.

Znotraj strani boste našli štiri datoteke s predlogami: približno.mdx, napredno.mdx, drugo.mdx, in index.mdx. Vsaka od teh datotek ustreza strani na spletnem mestu; na primer, index.mdx ustreza domači strani. URL lokalni gostitelj: 3000/približno odgovarja približno.mdx, in tako naprej.

V notranjosti strani, obstaja tudi mapa z imenom napredno, ki vsebuje eno datoteko z imenom satori.mdx. URL te datoteke bo lokalni gostitelj: 3000/napredno/satori.

Opazite, kako se vsaka od teh datotek konča z a .mdx razširitev.

Kaj je MDX?

Če imate izkušnje z Reactom, morate vedeti o JSX. To je HTML-ju podoben jezik, ki ga lahko uporabite za opis uporabniškega vmesnika komponent React.

MDX naloži, razčleni in upodablja JSX v dokumentu Markdown. Zahvaljujoč MDX lahko pišete komponente React in jih po potrebi uvozite v svoje dokumente Markdown. Datoteke MDX se končajo s pripono .mdx in lahko vključujejo Markdown in JSX.

MDX vam omogoča, da svoje znanje o Markdownu združite z Reactom, da ustvarite komponente za večkratno uporabo. Ti lahko ustvarite module CSS za oblikovanje komponent. To vam pomaga organizirati komponente za izboljšanje berljivosti in vzdrževanja.

Kako urediti obstoječe strani na dokumentacijskem mestu

Če želite urediti obstoječo stran, preprosto odprite ustrezno datoteko in jo spremenite. Podprta jezika sta Markdown in JSX.

Na primer, odprite index.mdx datoteko in zamenjajte vsebino s tem:

# Dobrodošli v moji dokumentaciji
Vesel sem, da te vidim tukaj. hvala
## Moja družabna omrežja
Sledite mi na [Twitter](https://twitter.com/kingchuuks) in [LinkedIn](https://linkedin.com/in/kingchuks)

Ta primer uporablja Markdown za oblikovanje vsebine. Vsebuje naslov prve ravni, naslov druge ravni in dve povezavi do družbenih medijev.

Shranite datoteko in obiščite domačo stran svojega dokumentacijskega mesta. Stran naj bi zdaj izgledala takole:

Na dnu strani lahko najdete tudi zadnji posodobljeni datum dokumenta.

Dodajanje nove strani

Preden dodate novo stran, se morate najprej odločiti, ali bo stran v strani/ imenik ali znotraj mape v njem. Uporabite mape, če želite kategorizirati svoje strani ali razviti hierarhijo.

V tem primeru ustvarite samostojno stran na najvišji ravni. Odpri datoteko z imenom namestitev.mdx v urejevalnik kode in vanj prilepite naslednjo kodo Markdown:

# Navodila za namestitev
Sledite temu vodniku, da namestite moj paket v svoj projekt
## 1. Namestite Node.js
Če želite namestiti Node.js, obiščite
[Stran z dokumentacijo Node.js](https://nodejs.org/en/download)

Shranite datoteko in preverite brskalnik. V stranskem meniju boste našli oznako za namestitev. Ko kliknete na povezavo, se prikaže vsebina namestitev.mdx upodablja na strani:

Spremenite lahko oznako in izvedete druge konfiguracije v datoteki _meta.json znotraj imenika strani. Če želite izvedeti več o tem, glejte Organizirajte datoteke del od Dokumentacija družbe Nextra.

Uporaba komponent React

Datoteke MDX lahko vključujejo JSX, ki je jezik, ki ga uporablja React. Komponento lahko ustvarite znotraj mape komponent in jo uvozite v kateri koli dokument na svojem spletnem mestu.

Primer, kako lahko vdelate komponente v Markdown, si lahko ogledate v drugo.mdx mapa:

## Komponenta
uvozi {useState} iz 'react'
uvozi sloge iz '../components/counters.module.css'
export const Counter = () => { 
 const [count, setCount] = useState (0); 


 vrnitev( 


 {count}-krat kliknjeno


)
}

<števec />

## Zunanje komponente
uvozi števce iz '../components/counters'

<Števci />

Ta datoteka Markdown vsebuje definicijo za komponento Counter. Po tem uvozi komponento Counters iz komponente imenik.

Če boste isto komponento uporabljali na svojem spletnem mestu z dokumentacijo, je najbolje, da jo ustvarite kot samostojno komponento in jo uvozite, ko jo potrebujete.

Izvedite več o Markdown

Če želite ustvariti vsebino za svoje spletno mesto z dokumentacijo, morate vedeti, kako uporabljati Markdown. Dobra novica je, da je sintakso Markdown zelo enostavno razumeti. Ko svoje znanje o Markdownu združite z Reactom, lahko ustvarite res robustna spletna mesta z dokumentacijo.