Nextra ļauj izveidot vietni dažu minūšu laikā, tāpēc tā ir lieliski piemērota dokumentu izplatīšanai jūsu komandai.

Ja esat iepazinies ar Next.js, varat to izmantot, lai viegli izstrādātu dokumentācijas vietni. Nextra ietvars parūpējas par sīkumiem jūsu vietā; viss, kas jums jādara, ir jāpievieno Markdown vai HTML saturs un YAML vai JSON dati.

Veiciet šīs darbības, lai izveidotu dokumentācijas vietni, izmantojot Nextra, uz Next.js balstītu statisko vietņu ģeneratoru. Jūs instalēsit un iestatīsit vajadzīgās atkarības, pēc tam uzzināsiet, kā pievienot jaunus dokumentus un lapas, rakstīt Markdown un iekļaut React komponentus.

Prasības dokumentu vietnes izveidei, izmantojot Nextra

Sāciet, instalējot Node.js, ja vēl neesat to izdarījis. The jaunākā Node.js versija nāk ar mezgla pakotņu pārvaldnieku npm, kas jums būs nepieciešams, lai instalētu šī projekta atkarības.

Papildus Node.js jums būs jāinstalē Git. Lai izvietotu vietni GitHub lapās, Netlify vai citā mitināšanas pakalpojumu sniedzējā, jums ir nepieciešams Git. Jums būs nepieciešams arī uzlabots koda redaktors, piemēram, VS Code.

instagram viewer

Nextra instalēšana

Jūs varat izmantot a nextra dokumentu veidne lai ielādētu dokumentācijas vietni. Palaidiet komandu uzvedni un dodieties uz direktoriju, kurā vēlaties iestatīt savu projektu. Pēc tam palaidiet šo komandu, lai ielādētu dokumentācijas vietni:

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

Šī komanda izveidos lietojumprogrammu pašreizējā direktorijā. Pēc tam palaidiet šo komandu, lai instalētu atkarības:

cd nextra-docs-template
npm instalēšana

Kad instalēšana ir pabeigta, palaidiet lietojumprogrammu. Dariet to, izpildot šo komandu savā terminālī:

npm palaist dev

Šī komanda palaiž izstrādes serveri vietnē localhost: 3000. Sekojiet saitei savā terminālī, lai skatītu dokumentācijas vietni. Mājas lapai vajadzētu izskatīties šādi:

Ja skatāties lapas kreisajā pusē, jūs atradīsit lapas ar nosaukumu Ievads un Vēl viena lapa. Zem šīm lapu saitēm jūs atradīsiet lapu ar nosaukumu Satori, kas ir ligzdotas iekšpusē Papildu (mape) direktoriju. Visbeidzot, navigācijas apgabalā jūs atradīsiet saites uz Par un Sazināties lapas.

Lai saprastu, kā šīs lapas darbojas, vispirms ir jāsaprot kā Next.js renderē lapas.

Izpratne par direktoriju struktūru

Tā kā Nextra izmanto ietvaru Next.js, tas atveido katru failu lapas/ mapi kā atsevišķu lapu.

Iekšpusē lapas direktorijā, jūs atradīsiet četrus veidņu failus: about.mdx, uzlabots.mdx, cits.mdx, un index.mdx. Katrs no šiem failiem atbilst kādai vietnes lapai; piemēram, index.mdx atbilst mājas lapai. URL localhost: 3000/aptuv attiecas uz about.mdx, un tā tālāk.

Iekšā lapas, ir arī mape ar nosaukumu uzlabotas, kurā atrodas viens fails ar nosaukumu satori.mdx. Šī faila URL būs localhost: 3000/advanced/satori.

Ievērojiet, kā katrs no šiem failiem beidzas ar a .mdx pagarinājumu.

Kas ir MDX?

Ja Jums ir pieredze ar React, jums vajadzētu zināt par JSX. Šī ir HTML līdzīga valoda, ko varat izmantot, lai aprakstītu React komponentu lietotāja interfeisu.

MDX ielādē, parsē un renderē JSX Markdown dokumentā. Pateicoties MDX, varat rakstīt React komponentus un vajadzības gadījumā importēt tos savos Markdown dokumentos. MDX faili beidzas ar paplašinājumu .mdx un var ietvert gan Markdown, gan JSX.

MDX ļauj apvienot zināšanas par Markdown ar React, lai izveidotu atkārtoti lietojamus komponentus. Jūs varat izveidot CSS moduļus veidot komponentus. Tas palīdz sakārtot komponentus, lai uzlabotu lasāmību un apkopi.

Kā rediģēt esošās lapas dokumentācijas vietnē

Lai rediģētu esošu lapu, vienkārši atveriet atbilstošo failu un veiciet tajā izmaiņas. Atbalstītās valodas ir Markdown un JSX.

Piemēram, atveriet index.mdx failu un aizstājiet saturu ar šo:

# Laipni lūdzam Manā dokumentācijā
Es priecājos jūs šeit redzēt. Paldies
## Mani sociālie tīkli
Sekojiet man vietnē [Twitter](https://twitter.com/kingchuuks) un [LinkedIn](https://linkedin.com/in/kingchuks)

Šajā piemērā satura formatēšanai tiek izmantota funkcija Markdown. Tajā ir pirmā līmeņa virsraksts, otrā līmeņa virsraksts un divas sociālo mediju saites.

Saglabājiet failu un apmeklējiet savas dokumentācijas vietnes sākumlapu. Lapai tagad vajadzētu izskatīties šādi:

Lapas apakšā varat atrast arī dokumenta pēdējo atjaunināto datumu.

Jaunas lapas pievienošana

Pirms jaunas lapas pievienošanas vispirms jāizlemj, vai lapa būs atrodama lapas/ direktorijā vai mapē tajā. Izmantojiet mapes, ja vēlaties klasificēt savas lapas vai izveidot hierarhiju.

Šādā gadījumā izveidojiet atsevišķu lapu augšējā līmenī. Atveriet failu ar nosaukumu install.mdx koda redaktorā un ielīmējiet tajā šādu Markdown kodu:

# Instalācijas rokasgrāmata
Izpildiet šo rokasgrāmatu, lai savā projektā instalētu manu pakotni
## 1. Instalējiet Node.js
Lai instalētu Node.js, apmeklējiet
[Node.js dokumentācijas vietne](https://nodejs.org/en/download)

Saglabājiet failu un pārbaudiet pārlūkprogrammu. Sānu izvēlnē atradīsit instalēšanas etiķeti. Noklikšķinot uz saites, saturs install.mdx atveido lapā:

Varat mainīt etiķeti un veikt citas konfigurācijas _meta.json failā, kas atrodas direktorijā lapas. Lai uzzinātu vairāk par to, skatiet Sakārtot failus sadaļa Nextra dokumentācija.

React komponentu izmantošana

MDX faili var ietvert JSX, kas ir valoda, ko izmanto React. Varat izveidot komponentu mapē komponenti un importēt to jebkurā savas vietnes dokumentā.

Varat redzēt piemēru, kā varat iegult komponentus Markdown vietnē cits.mdx fails:

## Komponents
importēt {useState} no 'react'
importēt stilus no '../components/counters.module.css'
eksporta konst Skaitītājs = () => { 
 const [skaits, setCount] = useState (0); 


 atgriezties ( 


 Noklikšķināts {count} reizes


)
}

<Skaitītājs />

## Ārējie komponenti
importēt skaitītājus no '../components/counters'

<Skaitītāji />

Šajā Markdown failā ir skaitītāja komponenta definīcija. Pēc tam tas importē komponentu Skaitītāji no sastāvdaļas direktoriju.

Ja plānojat izmantot vienu un to pašu komponentu savā dokumentācijas vietnē, vislabāk ir izveidot to kā atsevišķu komponentu un importēt, kad tas ir nepieciešams.

Uzziniet vairāk par Markdown

Lai izveidotu saturu savai dokumentācijas vietnei, jums jāzina, kā izmantot Markdown. Labā ziņa ir tā, ka Markdown sintaksi ir diezgan viegli uztvert. Apvienojot savas zināšanas par Markdown ar React, varat izveidot patiešām stabilas dokumentācijas vietnes.