Byg et Doc-websted med Next.js ved hjælp af Nextra

Hvis du er bekendt med Next.js, kan du bruge det til at udvikle et dokumentationswebsted med lethed. Nextra-rammen tager sig af det nøgnede for dig; alt du skal gøre er at tilføje Markdown- eller HTML-indhold og YAML- eller JSON-data.

Gå gennem disse trin for at bygge et dokumentationswebsted ved hjælp af Nextra, en Next.js-baseret statisk webstedsgenerator. Du installerer og konfigurerer de nødvendige afhængigheder og lærer derefter, hvordan du tilføjer nye dokumenter og sider, skriver Markdown og inkluderer React-komponenter.

Krav til opbygning af et Doc-websted med Nextra

Start med at installere Node.js, hvis du ikke allerede har gjort det. Det seneste Node.js version leveres med npm, node-pakkehåndteringen, som du skal bruge for at installere afhængigheder til dette projekt.

Udover Node.js skal du installere Git. Du skal bruge Git for at implementere webstedet til GitHub-sider, Netlify eller en anden hostingudbyder. Du skal også bruge en avanceret kodeeditor, såsom VS-kode.

Installation af Nextra

Du kan bruge en nextra docs skabelon at bootstrap et dokumentationssted. Start en kommandoprompt, og naviger til den mappe, hvor du vil konfigurere dit projekt. Kør derefter følgende kommando for at bootstrap dokumentationsstedet:

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

Denne kommando vil stilladsere et program inde i den aktuelle mappe. Kør derefter følgende kommando for at installere afhængighederne:

cd nextra-docs-skabelon
npm installere

Når installationen er fuldført, skal du starte applikationen. Gør det ved at køre følgende kommando på din terminal:

npm køre dev

Denne kommando starter en udviklingsserver på localhost: 3000. Følg linket på din terminal for at se dokumentationssiden. Hjemmesiden skal se sådan ud:

Hvis du kigger i venstre side af siden, finder du siderne med navn Introduktion og En anden side. Under disse sidelinks finder du en side ved navn Satori, indlejret inde i Avanceret (en mappe) vejviser. Endelig finder du i navigationsområdet links til Om og Kontakt sider.

For at forstå, hvordan disse sider fungerer, skal du først forstå hvordan Next.js gengiver sider.

Forståelse af mappestrukturen

Da Nextra bruger Next.js frameworket, gengiver den hver fil i sider/ mappe som en separat side.

Inde i sider mappe, finder du fire skabelonfiler: om.mdx, avanceret.mdx, en anden.mdx, og index.mdx. Hver af disse filer svarer til en side på webstedet; for eksempel, index.mdx svarer til hjemmesiden. URL'en lokalvært: 3000/ca svarer til om.mdx, og så videre.

Inde sider, er der også en mappe med navnet fremskreden, der rummer en enkelt fil med navnet satori.mdx. URL'en til denne fil vil være localhost: 3000/avanceret/satori.

Bemærk, hvordan hver af disse filer ender med en .mdx udvidelse.

Hvad er MDX?

Hvis du har erfaring med React, bør du vide om JSX. Dette er et HTML-lignende sprog, som du kan bruge til at beskrive brugerfladen af ​​React-komponenter.

MDX indlæser, analyserer og gengiver JSX i et Markdown-dokument. Takket være MDX kan du skrive React-komponenter og importere dem til dine Markdown-dokumenter, når det er nødvendigt. MDX-filer slutter med .mdx-udvidelsen og kan omfatte både Markdown og JSX.

MDX lader dig kombinere din viden om Markdown med React for at skabe genanvendelige komponenter. Du kan oprette CSS-moduler at style komponenterne. Dette hjælper dig med at organisere dine komponenter for at forbedre læsbarheden og vedligeholdelsen.

Sådan redigerer du eksisterende sider på dokumentationswebstedet

For at redigere en eksisterende side skal du blot åbne den tilsvarende fil og foretage ændringer i den. Understøttede sprog er Markdown og JSX.

Åbn f.eks index.mdx fil og erstat indholdet med dette:

# Velkommen til min dokumentation
Jeg er glad for at se dig her. Tak
## Mine sociale
Følg mig på [Twitter](https://twitter.com/kingchuuks) og [LinkedIn](https://linkedin.com/in/kingchuks)

Dette eksempel bruger Markdown til at formatere indholdet. Den indeholder en overskrift på niveau et, en overskrift på niveau to og to links til sociale medier.

Gem filen og besøg hjemmesiden på dit dokumentationswebsted. Siden skulle nu se sådan ud:

Nederst på siden kan du også finde dokumentets sidste opdateringsdato.

Tilføjelse af en ny side

Før du tilføjer en ny side, skal du først beslutte, om siden skal være i sider/ mappe eller inde i en mappe i den. Brug mapper, hvis du vil kategorisere dine sider eller udvikle et hierarki.

I dette tilfælde skal du oprette en selvstændig side på øverste niveau. Åbn en fil med navnet installation.mdx i din kodeeditor og indsæt følgende Markdown-kode i den:

# Installationsvejledning
Følg denne guide for at installere min pakke i dit projekt
## 1. Installer Node.js
For at installere Node.js skal du besøge
[Node.js dokumentationsside](https://nodejs.org/en/download)

Gem filen og tjek browseren. Du finder installationsetiketten i sidemenuen. Når du klikker på linket, vises indholdet af installation.mdx gengiver på siden:

Du kan ændre etiketten og udføre andre konfigurationer i filen _meta.json i pages-mappen. For at lære mere om dette, se Organiser filer afsnit af Nextras dokumentation.

Brug af React-komponenter

MDX-filer kan indeholde JSX, som er det sprog, som React bruger. Du kan oprette en komponent inde i mappen komponenter og importere den i et hvilket som helst af dokumenterne på dit websted.

Du kan se et eksempel på, hvordan du kan integrere komponenter i Markdown i en anden.mdx fil:

## Komponent
importer {useState} fra 'react'
importer typografier fra '../components/counters.module.css'
eksport konst Tæller = () => { 
 const [count, setCount] = useState (0); 
 Vend tilbage( 

 setCount (count+1)} className={styles.counter}> 
 Har klikket {count} gange