Bygg en Doc-webbplats med Next.js med Nextra

Om du är bekant med Next.js kan du använda den för att enkelt utveckla en dokumentationswebbplats. Nextra-ramverket tar hand om det nitty-gritty åt dig; allt du behöver göra är att lägga till Markdown- eller HTML-innehåll och YAML- eller JSON-data.

Gå igenom dessa steg för att bygga en dokumentationswebbplats med Nextra, en Next.js-baserad statisk webbplatsgenerator. Du kommer att installera och ställa in nödvändiga beroenden, sedan lära dig hur du lägger till nya dokument och sidor, skriver Markdown och inkluderar React-komponenter.

Krav för att bygga en Doc-webbplats med Nextra

Börja med att installera Node.js om du inte redan har gjort det. De senaste versionen av Node.js kommer med npm, nodpakethanteraren, som du behöver för att installera beroenden för det här projektet.

Förutom Node.js måste du installera Git. Du behöver Git för att distribuera webbplatsen till GitHub-sidor, Netlify eller en annan värdleverantör. Du behöver också en avancerad kodredigerare, till exempel VS Code.

Installerar Nextra

Du kan använda en nextra docs mall för att starta upp en dokumentationswebbplats. Starta en kommandotolk och navigera till katalogen där du vill ställa in ditt projekt. Kör sedan följande kommando för att bootstrap dokumentationsplatsen:

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

Detta kommando kommer att bygga ett program i den aktuella katalogen. Kör sedan följande kommando för att installera beroenden:

cd nextra-docs-mall
npm installera

När installationen är klar startar du programmet. Gör det genom att köra följande kommando på din terminal:

npm kör dev

Detta kommando startar en utvecklingsserver på localhost: 3000. Följ länken på din terminal för att se dokumentationswebbplatsen. Hemsidan ska se ut så här:

Om du tittar till vänster på sidan hittar du sidorna med namnet Introduktion och Ytterligare en sida. Under dessa sidlänkar hittar du en sida som heter Satori, kapslad inuti Avancerat (En mapp) katalog. Slutligen, i navigeringsområdet, hittar du länkar till Handla om och Kontakt sidor.

För att förstå hur dessa sidor fungerar måste du först förstå hur Next.js renderar sidor.

Förstå katalogstrukturen

Eftersom Nextra använder ramverket Next.js, renderar det varje fil i sidor/ mapp som en separat sida.

Inuti sidor katalog, hittar du fyra mallfiler: about.mdx, avancerad.mdx, another.mdx, och index.mdx. Var och en av dessa filer motsvarar en sida på webbplatsen; till exempel, index.mdx motsvarar startsidan. URL: en lokalvärd: 3000/ca motsvarar about.mdx, och så vidare.

Inuti sidor, det finns också en mapp som heter Avancerad, som innehåller en enda fil med namnet satori.mdx. URL: en för den här filen kommer att vara localhost: 3000/avancerad/satori.

Lägg märke till hur var och en av dessa filer slutar med en .mdx förlängning.

Vad är MDX?

Om du har erfarenhet av React, du borde veta om JSX. Detta är ett HTML-liknande språk som du kan använda för att beskriva användargränssnittet för React-komponenter.

MDX laddar, analyserar och renderar JSX i ett Markdown-dokument. Tack vare MDX kan du skriva React-komponenter och importera dem till dina Markdown-dokument när det behövs. MDX-filer slutar med tillägget .mdx och kan innehålla både Markdown och JSX.

MDX låter dig kombinera din kunskap om Markdown med React för att skapa återanvändbara komponenter. Du kan skapa CSS-moduler att styla komponenterna. Detta hjälper dig att organisera dina komponenter för att förbättra läsbarheten och underhållbarheten.

Hur man redigerar befintliga sidor på dokumentationswebbplatsen

För att redigera en befintlig sida öppnar du helt enkelt motsvarande fil och gör ändringar i den. Språk som stöds är Markdown och JSX.

Öppna till exempel index.mdx fil och ersätt innehållet med detta:

# Välkommen till min dokumentation
Jag är glad att se dig här. Tack
## My Socials
Följ mig på [Twitter](https://twitter.com/kingchuuks) och [LinkedIn](https://linkedin.com/in/kingchuks)

Det här exemplet använder Markdown för att formatera innehållet. Den innehåller en rubrik på nivå ett, en rubrik på nivå två och två länkar till sociala medier.

Spara filen och besök hemsidan för din dokumentationssida. Sidan ska nu se ut så här:

Längst ner på sidan hittar du även dokumentets senaste uppdateringsdatum.

Lägga till en ny sida

Innan du lägger till en ny sida måste du först bestämma om sidan ska finnas i sidor/ katalog eller i en mapp i den. Använd mappar om du vill kategorisera dina sidor eller utveckla en hierarki.

Skapa i det här fallet en fristående sida på översta nivån. Öppna en fil med namnet installation.mdx i din kodredigerare och klistra in följande Markdown-kod i den:

# Installationsguide
Följ den här guiden för att installera mitt paket i ditt projekt
## 1. Installera Node.js
För att installera Node.js, besök
[Node.js dokumentationswebbplats](https://nodejs.org/en/download)

Spara filen och kontrollera webbläsaren. Du hittar installationsetiketten i sidomenyn. När du klickar på länken visas innehållet i installation.mdx återger på sidan:

Du kan ändra etiketten och utföra andra konfigurationer i filen _meta.json i pages-katalogen. För att lära dig mer om detta, se Organisera filer avsnitt av Nextras dokumentation.

Använda React-komponenter

MDX-filer kan innehålla JSX, vilket är språket som React använder. Du kan skapa en komponent i komponentmappen och importera den i något av dokumenten på din webbplats.

Du kan se ett exempel på hur du kan bädda in komponenter i Markdown i another.mdx fil:

## Komponent
importera {useState} från 'react'
importera stilar från '../components/counters.module.css'
export const Counter = () => { 
 const [count, setCount] = useState (0); 
 lämna tillbaka( 

 setCount (count+1)} className={styles.counter}> 
 Klickade {count} gånger