Sukurkite dokumentų svetainę naudodami Next.js naudodami Nextra

Jei esate susipažinę su Next.js, galite jį naudoti kurdami dokumentacijos svetainę. „Nextra“ karkasas pasirūpins, kad viskas būtų gerai už jus; viskas, ką jums reikia padaryti, tai pridėti Markdown arba HTML turinį ir YAML arba JSON duomenis.

Atlikite šiuos veiksmus, kad sukurtumėte dokumentacijos svetainę naudodami Nextra, Next.js pagrįstą statinių svetainių generatorių. Įdiegsite ir nustatysite reikiamas priklausomybes, tada sužinosite, kaip pridėti naujų dokumentų ir puslapių, parašyti Markdown ir įtraukti React komponentus.

Reikalavimai kuriant dokumentų svetainę naudojant Nextra

Pradėkite diegdami Node.js, jei to dar nepadarėte. The naujausia Node.js versija ateina su npm, mazgo paketų tvarkykle, kurios jums reikės norint įdiegti šio projekto priklausomybes.

Be Node.js, turėsite įdiegti Git. Norint įdiegti svetainę į GitHub puslapius, „Netlify“ ar kitą prieglobos paslaugų teikėją, jums reikia „Git“. Jums taip pat reikės išplėstinio kodo rengyklės, pvz., „VS Code“.

„Nextra“ diegimas

Galite naudoti a nextra docs šablonas Norėdami paleisti dokumentacijos svetainę. Paleiskite komandų eilutę ir eikite į katalogą, kuriame norite nustatyti savo projektą. Tada paleiskite šią komandą, kad paleistumėte dokumentacijos svetainę:

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

Ši komanda sukurs programą dabartiniame kataloge. Tada paleiskite šią komandą, kad įdiegtumėte priklausomybes:

cd nextra-docs-template
npm diegimas

Kai diegimas bus baigtas, paleiskite programą. Padarykite tai savo terminale paleisdami šią komandą:

npm paleisti dev

Ši komanda paleidžia kūrimo serverį adresu localhost: 3000. Norėdami peržiūrėti dokumentų svetainę, spustelėkite savo terminale esančią nuorodą. Pagrindinis puslapis turėtų atrodyti taip:

Jei pažvelgsite į kairę puslapio pusę, rasite puslapius, pavadintus Įvadas ir Kitas puslapis. Po šiomis puslapių nuorodomis rasite puslapį pavadinimu Satori, įdėtą viduje Išplėstinė (aplankas) katalogas. Galiausiai naršymo srityje rasite nuorodas į Apie ir kontaktas puslapių.

Norėdami suprasti, kaip šie puslapiai veikia, pirmiausia turite suprasti kaip Next.js pateikia puslapius.

Suprasti katalogo struktūrą

Kadangi „Nextra“ naudoja „Next.js“ sistemą, ji pateikia kiekvieną failą puslapiai/ aplanką kaip atskirą puslapį.

Viduje puslapių kataloge, rasite keturis šablonų failus: apie.mdx, išplėstinis.mdx, kitas.mdx, ir index.mdx. Kiekvienas iš šių failų atitinka svetainės puslapį; pavyzdžiui, index.mdx atitinka pagrindinį puslapį. URL localhost: 3000/apie atitinka apie.mdx, ir taip toliau.

Viduje puslapių, taip pat yra aplankas pavadinimu pažengęs, kuriame yra vienas failas pavadinimu satori.mdx. Šio failo URL bus Localhost: 3000/Advanced/satori.

Atkreipkite dėmesį, kaip kiekvienas iš šių failų baigiasi raide a .mdx pratęsimas.

Kas yra MDX?

Jei turite patirtis su React, turėtumėte žinoti apie JSX. Tai į HTML panaši kalba, kurią galite naudoti „React“ komponentų vartotojo sąsajai apibūdinti.

MDX įkelia, analizuoja ir atvaizduoja JSX Markdown dokumente. MDX dėka galite rašyti „React“ komponentus ir prireikus importuoti juos į „Markdown“ dokumentus. MDX failai baigiasi .mdx plėtiniu ir gali apimti ir Markdown, ir JSX.

MDX leidžia sujungti savo žinias apie Markdown su React ir sukurti daugkartinio naudojimo komponentus. Tu gali sukurti CSS modulius stilizuoti komponentus. Tai padeda tvarkyti komponentus, kad būtų lengviau skaitoma ir lengviau prižiūrėti.

Kaip redaguoti esamus puslapius dokumentacijos svetainėje

Norėdami redaguoti esamą puslapį, tiesiog atidarykite atitinkamą failą ir pakeiskite jį. Palaikomos kalbos yra Markdown ir JSX.

Pavyzdžiui, atidarykite index.mdx failą ir pakeiskite turinį šiuo:

# Sveiki atvykę į mano dokumentaciją
Džiaugiuosi tave čia matydamas. Dėkoju
## Mano socialiniai tinklai
Sek mane [Twitter](https://twitter.com/kingchuuks) ir [LinkedIn](https://linkedin.com/in/kingchuks)

Šiame pavyzdyje turiniui formatuoti naudojamas Markdown. Jame yra pirmojo lygio antraštė, antrojo lygio antraštė ir dvi socialinės žiniasklaidos nuorodos.

Išsaugokite failą ir apsilankykite dokumentacijos svetainės pagrindiniame puslapyje. Dabar puslapis turėtų atrodyti taip:

Puslapio apačioje taip pat galite rasti dokumento paskutinį kartą atnaujintą datą.

Naujo puslapio pridėjimas

Prieš įtraukdami naują puslapį, pirmiausia turite nuspręsti, ar puslapis bus puslapiai/ kataloge arba jame esančiame aplanke. Naudokite aplankus, jei norite suskirstyti puslapius į kategorijas arba sukurti hierarchiją.

Tokiu atveju sukurkite atskirą puslapį viršutiniame lygyje. Atidarykite failą pavadinimu diegimas.mdx savo kodo rengyklėje ir įklijuokite į jį šį Markdown kodą:

# Diegimo vadovas
Vadovaukitės šiuo vadovu, kad įdiegtumėte mano paketą savo projekte
## 1. Įdiekite Node.js
Norėdami įdiegti Node.js, apsilankykite
[Node.js dokumentacijos svetainė](https://nodejs.org/en/download)

Išsaugokite failą ir patikrinkite naršyklę. Diegimo etiketę rasite šoniniame meniu. Kai paspausite ant nuorodos, turinys diegimas.mdx pateikia puslapyje:

Galite pakeisti etiketę ir atlikti kitas konfigūracijas _meta.json faile puslapių kataloge. Norėdami sužinoti daugiau apie tai, žr Tvarkyti failus skyrių Nextra dokumentacija.

React komponentų naudojimas

MDX failuose gali būti JSX, kuri yra React naudojama kalba. Galite sukurti komponentą komponentų aplanke ir importuoti jį į bet kurį savo svetainės dokumentą.

Galite pamatyti pavyzdį, kaip galite įterpti komponentus į Markdown kitas.mdx failas:

## Komponentas
importuoti {useState} iš „react“
importuoti stilius iš „../components/counters.module.css“
eksportuoti const Skaitliukas = () => { 
 const [count, setCount] = useState (0); 
 grįžti ( 

 setCount (count+1)} className={styles.counter}> 
 Spustelėta {count} kartus