Luo asiakirjasivusto Next.js: n avulla Nextran avulla

Jos Next.js on sinulle tuttu, voit käyttää sitä dokumentaatiosivuston kehittämiseen helposti. Nextra-kehys huolehtii nihkeästä puolestasi; sinun tarvitsee vain lisätä Markdown- tai HTML-sisältöä ja YAML- tai JSON-tietoja.

Käy läpi nämä vaiheet luodaksesi dokumentaatiosivuston Nextralla, Next.js-pohjaisella staattisen sivuston luontiohjelmalla. Asennat ja määrität tarvittavat riippuvuudet ja opit sitten lisäämään uusia asiakirjoja ja sivuja, kirjoittamaan Markdownia ja sisällyttämään React-komponentteja.

Vaatimukset dokumenttisivuston rakentamiselle Nextran avulla

Aloita asentamalla Node.js, jos et ole jo tehnyt niin. The uusin Node.js-versio mukana tulee npm, solmupakettien hallinta, jota tarvitset tämän projektin riippuvuuksien asentamiseen.

Node.js: n lisäksi sinun on asennettava Git. Tarvitset Gitin, jotta voit ottaa sivuston käyttöön GitHub-sivuilla, Netlifyssa tai toisessa isännöintipalveluntarjoajassa. Tarvitset myös edistyneen koodieditorin, kuten VS Coden.

Nextran asennus

Voit käyttää a nextra docs -malli käynnistääksesi dokumentaatiosivuston. Käynnistä komentokehote ja siirry hakemistoon, johon haluat määrittää projektin. Käynnistä sitten dokumentaatiosivusto suorittamalla seuraava komento:

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

Tämä komento rakentaa sovelluksen nykyiseen hakemistoon. Suorita seuraavaksi seuraava komento asentaaksesi riippuvuudet:

cd nextra-docs-template
npm asennus

Kun asennus on valmis, käynnistä sovellus. Tee se suorittamalla seuraava komento päätteessäsi:

npm run dev

Tämä komento käynnistää kehityspalvelimen osoitteessa localhost: 3000. Seuraa terminaalissasi olevaa linkkiä nähdäksesi dokumentaatiosivuston. Kotisivun pitäisi näyttää tältä:

Jos katsot sivun vasenta reunaa, löydät nimetyt sivut Johdanto ja Toinen sivu. Näiden sivulinkkien alta löydät Satori-nimisen sivun sisäkkäin Lisäasetukset (A-kansio) hakemistosta. Lopuksi navigointialueelta löydät linkkejä osoitteeseen Noin ja Ottaa yhteyttä sivuja.

Ymmärtääksesi kuinka nämä sivut toimivat, sinun on ensin ymmärrettävä miten Next.js hahmontaa sivut.

Hakemistorakenteen ymmärtäminen

Koska Nextra käyttää Next.js-kehystä, se hahmontaa jokaisen tiedoston sivut/ kansio erillisenä sivuna.

Sisällä sivuja hakemistosta löydät neljä mallitiedostoa: about.mdx, advanced.mdx, toinen.mdx, ja index.mdx. Jokainen näistä tiedostoista vastaa verkkosivuston sivua; esimerkiksi, index.mdx vastaa kotisivua. URL-osoite localhost: 3000/n vastaa about.mdx, ja niin edelleen.

Sisällä sivuja, siellä on myös kansio nimeltä pitkälle kehittynyt, jossa on yksi tiedosto nimeltä satori.mdx. Tämän tiedoston URL-osoite on localhost: 3000/advanced/satori.

Huomaa, kuinka kukin näistä tiedostoista päättyy kirjaimeen a .mdx laajennus.

Mikä on MDX?

Jos sinulla on kokemusta Reactista, sinun pitäisi tietää JSX. Tämä on HTML: n kaltainen kieli, jota voit käyttää kuvaamaan React-komponenttien käyttöliittymää.

MDX lataa, jäsentää ja hahmontaa JSX: n Markdown-asiakirjassa. MDX: n ansiosta voit kirjoittaa React-komponentteja ja tuoda ne tarvittaessa Markdown-asiakirjoihin. MDX-tiedostot päättyvät .mdx-tunnisteella ja voivat sisältää sekä Markdownin että JSX: n.

MDX: n avulla voit yhdistää Markdown-tietosi Reactiin luodaksesi uudelleenkäytettäviä komponentteja. Sinä pystyt luoda CSS-moduuleja komponenttien tyyliin. Tämä auttaa sinua järjestämään komponentit luettavuuden ja ylläpidettävyyden parantamiseksi.

Dokumentaatiosivuston olemassa olevien sivujen muokkaaminen

Jos haluat muokata olemassa olevaa sivua, avaa vain vastaava tiedosto ja tee siihen muutoksia. Tuetut kielet ovat Markdown ja JSX.

Avaa esimerkiksi index.mdx tiedosto ja korvaa sisältö tällä:

# Tervetuloa dokumentaatiooni
Olen iloinen nähdessäni sinut täällä. Kiitos
## Socials
Seuraa minua [Viserrys](https://twitter.com/kingchuuks) ja [LinkedIn](https://linkedin.com/in/kingchuks)

Tämä esimerkki käyttää Markdownia sisällön muotoiluun. Se sisältää ensimmäisen tason otsikon, tason kaksi otsikon ja kaksi sosiaalisen median linkkiä.

Tallenna tiedosto ja vieraile dokumentaatiosivustosi kotisivulla. Sivun pitäisi nyt näyttää tältä:

Sivun alalaidasta löydät myös asiakirjan viimeisimmän päivityspäivämäärän.

Uuden sivun lisääminen

Ennen kuin lisäät uuden sivun, sinun on ensin päätettävä, onko sivu mukana sivut/ hakemistossa tai sen sisällä olevan kansion sisällä. Käytä kansioita, jos haluat luokitella sivusi tai kehittää hierarkiaa.

Luo tässä tapauksessa erillinen sivu ylimmälle tasolle. Avaa tiedosto nimeltä install.mdx koodieditorissasi ja liitä siihen seuraava Markdown-koodi:

# Asennusohje
Noudata tätä opasta asentaaksesi pakettini projektiisi
## 1. Asenna Node.js
Asenna Node.js käymällä osoitteessa
[Node.js-dokumentaatiosivusto](https://nodejs.org/en/download)

Tallenna tiedosto ja tarkista selain. Asennusmerkintä löytyy sivuvalikosta. Kun napsautat linkkiä, sisältö näkyy install.mdx renderöi sivulla:

Voit muuttaa nimiötä ja tehdä muita määrityksiä _meta.json-tiedostossa sivuhakemistossa. Lisätietoja tästä on osoitteessa Järjestä tiedostot osio Nextran dokumentaatio.

React-komponenttien käyttäminen

MDX-tiedostot voivat sisältää JSX: n, joka on Reactin käyttämä kieli. Voit luoda komponentin komponenttien kansioon ja tuoda sen mihin tahansa sivustosi asiakirjoihin.

Voit nähdä esimerkin siitä, kuinka voit upottaa komponentteja Markdowniin toinen.mdx tiedosto:

## Komponentti
tuo {useState} kohdasta "react"
tuo tyylejä osoitteesta "../components/counters.module.css"
vienti const Laskuri = () => { 
 const [count, setCount] = useState (0); 
 palata( 

 setCount (count+1)} className={styles.counter}> 
 Klikattiin {count} kertaa