Bygg en Doc-side med Next.js ved å bruke Nextra

Hvis du er kjent med Next.js, kan du bruke den til å utvikle et dokumentasjonsnettsted med letthet. Nextra-rammeverket tar seg av det nitty-gritty for deg; alt du trenger å gjøre er å legge til Markdown- eller HTML-innhold og YAML- eller JSON-data.

Gå gjennom disse trinnene for å bygge et dokumentasjonsnettsted ved å bruke Nextra, en Next.js-basert statisk nettstedsgenerator. Du vil installere og sette opp de nødvendige avhengighetene, og deretter lære hvordan du legger til nye dokumenter og sider, skriver Markdown og inkluderer React-komponenter.

Krav for å bygge en Doc-side med Nextra

Start med å installere Node.js hvis du ikke allerede har gjort det. De siste versjon av Node.js kommer med npm, nodepakkebehandleren, som du trenger for å installere avhengigheter for dette prosjektet.

I tillegg til Node.js, må du installere Git. Du trenger Git for å distribuere nettstedet til GitHub-sider, Netlify eller en annen vertsleverandør. Du trenger også en avansert koderedigerer, for eksempel VS-kode.

Installerer Nextra

Du kan bruke en nextra docs mal å starte opp et dokumentasjonsnettsted. Start en ledetekst og naviger til katalogen der du vil sette opp prosjektet. Kjør deretter følgende kommando for å starte opp dokumentasjonssiden:

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

Denne kommandoen vil stillas et program inne i gjeldende katalog. Kjør deretter følgende kommando for å installere avhengighetene:

cd nextra-docs-mal
npm installere

Når installasjonen er fullført, start applikasjonen. Gjør det ved å kjøre følgende kommando på terminalen din:

npm kjøre dev

Denne kommandoen starter en utviklingsserver på localhost: 3000. Følg koblingen på terminalen for å se dokumentasjonssiden. Hjemmesiden skal se slik ut:

Hvis du ser på venstre side av siden, finner du sidene med navn Introduksjon og En annen side. Under disse sidelenkene finner du en side som heter Satori, nestet inne i Avansert (en mappe) katalog. Til slutt, i navigasjonsområdet, finner du lenker til Om og Kontakt sider.

For å forstå hvordan disse sidene fungerer, må du først forstå hvordan Next.js gjengir sider.

Forstå katalogstrukturen

Siden Nextra bruker Next.js-rammeverket, gjengir det hver fil i sider/ mappe som en egen side.

Inne i sider katalog, finner du fire malfiler: about.mdx, avansert.mdx, en annen.mdx, og index.mdx. Hver av disse filene tilsvarer en side på nettstedet; for eksempel, index.mdx tilsvarer hjemmesiden. URL-en lokalvert: 3000/ca tilsvarer about.mdx, og så videre.

Innsiden sider, det er også en mappe som heter avansert, som inneholder en enkelt fil med navn satori.mdx. URL for denne filen vil være localhost: 3000/advanced/satori.

Legg merke til hvordan hver av disse filene ender med en .mdx Utvidelse.

Hva er MDX?

Hvis du har erfaring med React, bør du vite om JSX. Dette er et HTML-lignende språk som du kan bruke til å beskrive brukergrensesnittet til React-komponenter.

MDX laster inn, analyserer og gjengir JSX i et Markdown-dokument. Takket være MDX kan du skrive React-komponenter og importere dem til Markdown-dokumentene dine når det er nødvendig. MDX-filer slutter med .mdx-utvidelsen og kan inkludere både Markdown og JSX.

MDX lar deg kombinere kunnskapen din om Markdown med React for å lage gjenbrukbare komponenter. Du kan lage CSS-moduler å style komponentene. Dette hjelper deg med å organisere komponentene dine for å forbedre lesbarhet og vedlikehold.

Hvordan redigere eksisterende sider på dokumentasjonssiden

For å redigere en eksisterende side, åpner du den tilhørende filen og gjør endringer i den. Støttede språk er Markdown og JSX.

Åpne for eksempel index.mdx fil og erstatt innholdet med dette:

# Velkommen til min dokumentasjon
Jeg er glad for å se deg her. Takk
## My Socials
Følg meg på [Twitter](https://twitter.com/kingchuuks) og [LinkedIn](https://linkedin.com/in/kingchuks)

Dette eksemplet bruker Markdown til å formatere innholdet. Den inneholder en overskrift på nivå én, en overskrift på nivå to og to linker til sosiale medier.

Lagre filen og besøk hjemmesiden til dokumentasjonssiden. Siden skal nå se slik ut:

Nederst på siden finner du også dokumentets siste oppdateringsdato.

Legger til en ny side

Før du legger til en ny side, må du først bestemme om siden skal være i sider/ katalog eller inne i en mappe i den. Bruk mapper hvis du vil kategorisere sidene dine eller utvikle et hierarki.

I dette tilfellet oppretter du en frittstående side på toppnivå. Åpne en fil med navnet installasjon.mdx i kodeeditoren og lim inn følgende Markdown-kode i den:

# Installasjonsveiledning
Følg denne veiledningen for å installere pakken min i prosjektet ditt
## 1. Installer Node.js
For å installere Node.js, gå til
[Node.js dokumentasjonsside](https://nodejs.org/en/download)

Lagre filen og sjekk nettleseren. Du finner installasjonsetiketten i sidemenyen. Når du klikker på lenken vil innholdet i installasjon.mdx gjengir på siden:

Du kan endre etiketten og utføre andre konfigurasjoner i _meta.json-filen i sidekatalogen. For å lære mer om dette, se Organiser filer delen av Nextras dokumentasjon.

Bruke React-komponenter

MDX-filer kan inkludere JSX, som er språket som React bruker. Du kan opprette en komponent i komponenter-mappen og importere den i alle dokumentene på nettstedet ditt.

Du kan se et eksempel på hvordan du kan bygge inn komponenter i Markdown i en annen.mdx fil:

## Komponent
importer {useState} fra 'react'
importer stiler fra '../components/counters.module.css'
eksportkonst Teller = () => { 
 const [count, setCount] = useState (0); 
 komme tilbake( 

 setCount (count+1)} className={styles.counter}> 
 Klikket {count} ganger