Looge Next.js-iga dokumendisait, kasutades Nextrat

Kui olete Next.js-iga tuttav, saate seda kasutada dokumentatsioonisaidi hõlpsaks väljatöötamiseks. Nextra raamistik hoolitseb selle eest, et see oleks teie jaoks ülim. kõik, mida pead tegema, on lisada Markdowni või HTML-i sisu ja YAML- või JSON-andmed.

Järgige neid samme dokumentatsiooni saidi koostamiseks, kasutades Next.js-põhise staatilise saidi generaatorit Nextrat. Installite ja seadistate vajalikud sõltuvused, seejärel õpite uusi dokumente ja lehti lisama, Markdowni kirjutama ja Reacti komponente kaasama.

Nõuded Nextraga dokumendisaidi ehitamiseks

Alustuseks installige Node.js, kui te pole seda veel teinud. The uusim Node.js versioon kaasas npm, sõlmede paketihaldur, mida peate selle projekti jaoks sõltuvuste installimiseks.

Lisaks Node.js-ile peate installima Git. Saidi GitHubi lehtedele, Netlifyle või mõnele muule hostiteenuse pakkujale juurutamiseks vajate Giti. Teil on vaja ka täiustatud koodiredaktorit, näiteks VS-koodi.

Nextra installimine

Võite kasutada a nextra docsi mall dokumentatsiooni saidi alglaadimiseks. Käivitage käsuviip ja liikuge kataloogi, kuhu soovite oma projekti seadistada. Seejärel käivitage dokumentatsiooni saidi alglaadimiseks järgmine käsk:

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

See käsk koondab praeguses kataloogis oleva rakenduse. Järgmisena käivitage sõltuvuste installimiseks järgmine käsk:

cd nextra-docs-template
npm installimine

Kui installimine on lõppenud, käivitage rakendus. Tehke seda, käivitades oma terminalis järgmise käsu:

npm käivita dev

See käsk käivitab arendusserveri aadressil localhost: 3000. Dokumentatsiooni saidi vaatamiseks järgige terminalis olevat linki. Koduleht peaks välja nägema selline:

Kui vaatate lehe vasakut serva, leiate nimega lehed Sissejuhatus ja Teine leht. Nende lehelinkide alt leiate lehe nimega Satori, mis on pesastatud lehe sisse Täpsem (kaust) kataloog. Lõpuks leiate navigeerimisalast lingid Umbes ja Võtke ühendust lehekülgi.

Et mõista, kuidas need lehed töötavad, peate esmalt mõistma kuidas Next.js lehti renderdab.

Kataloogistruktuuri mõistmine

Kuna Nextra kasutab Next.js raamistikku, renderdab see iga faili lehekülge/ kausta eraldi lehena.

Sees lehekülgi kataloogist leiate neli mallifaili: about.mdx, täiustatud.mdx, teine.mdx, ja index.mdx. Kõik need failid vastavad veebisaidi lehele; näiteks, index.mdx vastab avalehele. URL localhost: 3000/umbes vastab about.mdx, ja nii edasi.

Sees lehekülgi, seal on ka kaust nimega edasijõudnud, mis sisaldab ühte faili nimega satori.mdx. Selle faili URL on localhost: 3000/advanced/satori.

Pange tähele, kuidas kõik need failid lõppevad tähega a .mdx pikendamine.

Mis on MDX?

Kui teil on kogemus Reactiga, peaksite JSX-i kohta teadma. See on HTML-i sarnane keel, mida saate kasutada Reacti komponentide kasutajaliidese kirjeldamiseks.

MDX laadib, analüüsib ja renderdab JSX-i Markdowni dokumendis. Tänu MDX-le saate kirjutada Reacti komponente ja importida need vajadusel oma Markdowni dokumentidesse. MDX-failid lõpevad laiendiga .mdx ja võivad sisaldada nii Markdowni kui ka JSX-i.

MDX võimaldab teil ühendada oma teadmised Markdownist Reactiga, et luua korduvkasutatavaid komponente. Sa saad luua CSS-mooduleid komponentide stiiliks. See aitab teil oma komponente korrastada, et parandada loetavust ja hooldatavust.

Kuidas dokumentatsiooni saidil olemasolevaid lehti redigeerida

Olemasoleva lehe muutmiseks avage lihtsalt vastav fail ja tehke selles muudatused. Toetatud keeled on Markdown ja JSX.

Näiteks avage index.mdx faili ja asendage sisu järgmisega:

# Tere tulemast minu dokumentatsiooni
Mul on hea meel teid siin näha. Aitäh
## Minu suhtlusvõrgustikud
Jälgi mind saidil [Twitter](https://twitter.com/kingchuuks) ja [LinkedIn](https://linkedin.com/in/kingchuks)

See näide kasutab sisu vormindamiseks funktsiooni Markdown. See sisaldab esimese taseme pealkirja, teise taseme pealkirja ja kahte sotsiaalmeedia linki.

Salvestage fail ja külastage oma dokumentatsiooni saidi kodulehte. Leht peaks nüüd välja nägema selline:

Lehe allservast leiate ka dokumendi viimati uuendatud kuupäeva.

Uue lehe lisamine

Enne uue lehe lisamist peate esmalt otsustama, kas leht on lehekülge/ kataloogis või selles olevas kaustas. Kasutage kaustu, kui soovite oma lehti kategoriseerida või hierarhiat välja töötada.

Sel juhul looge ülemisel tasemel iseseisev leht. Avage fail nimega install.mdx oma koodiredaktorisse ja kleepige sinna järgmine Markdowni kood:

# Paigaldusjuhend
Järgige seda juhendit, et installida minu pakett oma projekti
## 1. Installige Node.js
Node.js installimiseks külastage
[Node.js dokumentatsioonisait](https://nodejs.org/en/download)

Salvestage fail ja kontrollige brauserit. Külgmenüüst leiate installisildi. Kui klõpsate lingil, sisu install.mdx renderdab lehel:

Saate muuta silti ja teha muid konfiguratsioone lehtede kataloogis olevas failis _meta.json. Selle kohta lisateabe saamiseks vaadake Failide korraldamine osa Nextra dokumentatsioon.

React komponentide kasutamine

MDX-failid võivad sisaldada JSX-i, mis on Reacti kasutatav keel. Saate luua komponendi komponentide kaustas ja importida selle oma saidi mis tahes dokumenti.

Näete näidet selle kohta, kuidas saate Markdowni komponente manustada rakenduses teine.mdx fail:

## Komponent
import {useState} 'react'ist
laadide importimine saidilt ../components/counters.module.css
ekspordi konst Loendur = () => { 
 const [loendus, setCount] = useState (0); 
 tagasi ( 

 setCount (count+1)} className={styles.counter}> 
 Klõpsati {count} korda