Bouw een Doc-site met Next.js met behulp van Nextra

Als u bekend bent met Next.js, kunt u het gebruiken om gemakkelijk een documentatiesite te ontwikkelen. Het Nextra-framework regelt de kern van de zaak voor u; het enige dat u hoeft te doen, is Markdown- of HTML-inhoud en YAML- of JSON-gegevens toevoegen.

Doorloop deze stappen om een ​​documentatiesite te bouwen met behulp van Nextra, een op Next.js gebaseerde statische sitegenerator. U installeert en stelt de benodigde afhankelijkheden in, leert vervolgens hoe u nieuwe documenten en pagina's toevoegt, Markdown schrijft en React-componenten opneemt.

Vereisten voor het bouwen van een Doc-site met Nextra

Begin met het installeren van Node.js als je dat nog niet hebt gedaan. De nieuwste Node.js-versie wordt geleverd met npm, de knooppuntpakketbeheerder, die u nodig hebt om afhankelijkheden voor dit project te installeren.

Naast Node.js moet u installeren Git. Je hebt Git nodig om de site te implementeren op GitHub-pagina's, Netlify of een andere hostingprovider. Je hebt ook een geavanceerde code-editor nodig, zoals VS Code.

Nextra installeren

U kunt een nextra docs-sjabloon om een ​​documentatiesite op te starten. Start een opdrachtprompt en navigeer naar de map waarin u uw project wilt opzetten. Voer vervolgens de volgende opdracht uit om de documentatiesite op te starten:

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

Met deze opdracht wordt een toepassing in de huidige map ondersteund. Voer vervolgens de volgende opdracht uit om de afhankelijkheden te installeren:

cd nextra-docs-sjabloon
npm installeren

Zodra de installatie is voltooid, start u de toepassing. Doe dit door de volgende opdracht op uw terminal uit te voeren:

npm run dev

Deze opdracht start een ontwikkelingsserver op localhost: 3000. Volg de link op uw terminal om de documentatiesite te bekijken. De startpagina zou er als volgt uit moeten zien:

Als u aan de linkerkant van de pagina kijkt, vindt u de pagina's met een naam Invoering En Een andere pagina. Onder deze paginalinks vindt u een pagina met de naam Satori, genest in de Geavanceerd (een map) map. Ten slotte vindt u in het navigatiegebied links naar de Over En Contact Pagina's.

Om te begrijpen hoe deze pagina's werken, moet u eerst begrijpen hoe Next.js pagina's weergeeft.

De directorystructuur begrijpen

Aangezien Nextra het Next.js-framework gebruikt, wordt elk bestand in de Pagina's/ map als een aparte pagina.

Binnen in de Pagina's directory vindt u vier sjabloonbestanden: over.mdx, geavanceerd.mdx, een andere.mdx, En index.mdx. Elk van deze bestanden komt overeen met een pagina op de website; Bijvoorbeeld, index.mdx komt overeen met de startpagina. De URL localhost: 3000/ongeveer komt overeen met over.mdx, enzovoort.

Binnen Pagina's, er is ook een map met de naam geavanceerd, waarin een enkel bestand met de naam satori.mdx. De URL voor dit bestand zal zijn localhost: 3000/geavanceerd/satori.

Merk op hoe elk van deze bestanden eindigt met een .mdx verlenging.

Wat is MDX?

Als je hebt ervaring met React, zou je moeten weten over JSX. Dit is een HTML-achtige taal die u kunt gebruiken om de gebruikersinterface van React-componenten te beschrijven.

MDX laadt, parseert en rendert JSX in een Markdown-document. Dankzij MDX kun je React-componenten schrijven en deze indien nodig in je Markdown-documenten importeren. MDX-bestanden eindigen met de extensie .mdx en kunnen zowel Markdown als JSX bevatten.

Met MDX kun je je kennis van Markdown combineren met React om herbruikbare componenten te maken. Jij kan CSS-modules maken om de componenten te stylen. Dit helpt u bij het organiseren van uw componenten om de leesbaarheid en onderhoudbaarheid te verbeteren.

Bestaande pagina's op de documentatiesite bewerken

Om een ​​bestaande pagina te bewerken, opent u gewoon het bijbehorende bestand en brengt u er wijzigingen in aan. Ondersteunde talen zijn Markdown en JSX.

Open bijvoorbeeld de index.mdx bestand en vervang de inhoud door dit:

# Welkom bij mijn documentatie
Ik ben blij je hier te zien. Bedankt
## Mijn sociale contacten
Volg me op [Twitteren](https://twitter.com/kingchuuks) En [LinkedIn](https://linkedin.com/in/kingchuks)

In dit voorbeeld wordt Markdown gebruikt om de inhoud op te maken. Het bevat een kop van niveau één, een kop van niveau twee en twee links naar sociale media.

Sla het bestand op en bezoek de startpagina van uw documentatiesite. De pagina zou er nu zo uit moeten zien:

Onderaan de pagina vindt u ook de laatste updatedatum van het document.

Een nieuwe pagina toevoegen

Voordat u een nieuwe pagina toevoegt, moet u eerst beslissen of de pagina in de Pagina's/ directory of in een map daarin. Gebruik mappen als u uw pagina's wilt categoriseren of een hiërarchie wilt ontwikkelen.

Maak in dit geval een zelfstandige pagina op het hoogste niveau. Open een bestand met de naam installatie.mdx in uw code-editor en plak de volgende Markdown-code erin:

# Installatie gids
Volg deze gids om mijn pakket in uw project te installeren
## 1. Installeer Node.js
Om Node.js te installeren, gaat u naar de
[Node.js documentatiesite](https://nodejs.org/en/download)

Sla het bestand op en controleer de browser. Je vindt het installatielabel in het zijmenu. Wanneer u op de link klikt, wordt de inhoud van installatie.mdx geeft weer op de pagina:

U kunt het label wijzigen en andere configuraties uitvoeren in het bestand _meta.json in de directory Pages. Voor meer informatie hierover, zie de Organiseer bestanden gedeelte van documentatie van Nextra.

React-componenten gebruiken

MDX-bestanden kunnen JSX bevatten, de taal die React gebruikt. U kunt een component maken in de map Components en deze importeren in een van de documenten op uw site.

U kunt een voorbeeld zien van hoe u componenten in Markdown kunt insluiten in de een andere.mdx bestand:

## Onderdeel
importeer {useState} van 'react'
importeer stijlen uit '../components/counters.module.css'
export const Teller = () => { 
 const [telling, setCount] = useState (0); 
 opbrengst( 

 setCount (count+1)} className={styles.counter}> 
 {count} keer geklikt