Erstellen Sie mit Nextra eine Doc-Site mit Next.js

Wenn Sie mit Next.js vertraut sind, können Sie damit problemlos eine Dokumentationssite entwickeln. Das Nextra-Framework kümmert sich für Sie um das Wesentliche; Sie müssen lediglich Markdown- oder HTML-Inhalte und YAML- oder JSON-Daten hinzufügen.

Gehen Sie diese Schritte durch, um eine Dokumentationssite mit Nextra, einem auf Next.js basierenden Generator für statische Sites, zu erstellen. Sie installieren und richten die erforderlichen Abhängigkeiten ein und lernen dann, wie Sie neue Dokumente und Seiten hinzufügen, Markdown schreiben und React-Komponenten einbinden.

Anforderungen zum Erstellen einer Doc-Site mit Nextra

Beginnen Sie mit der Installation von Node.js, falls Sie dies noch nicht getan haben. Der neueste Node.js-Version kommt mit npm, dem Node Package Manager, den Sie benötigen, um Abhängigkeiten für dieses Projekt zu installieren.

Neben Node.js müssen Sie es installieren

Git. Sie benötigen Git, um die Site auf GitHub-Seiten, Netlify oder einem anderen Hosting-Anbieter bereitzustellen. Sie benötigen außerdem einen erweiterten Code-Editor wie VS Code.

Nextra installieren

Sie können eine verwenden Nextra-Docs-Vorlage um eine Dokumentationsseite zu booten. Starten Sie eine Eingabeaufforderung und navigieren Sie zu dem Verzeichnis, in dem Sie Ihr Projekt einrichten möchten. Führen Sie dann den folgenden Befehl aus, um die Dokumentationsseite zu booten:

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

Dieser Befehl baut eine Anwendung innerhalb des aktuellen Verzeichnisses auf. Führen Sie als Nächstes den folgenden Befehl aus, um die Abhängigkeiten zu installieren:

cd nextra-docs-template
npm installieren

Starten Sie nach Abschluss der Installation die Anwendung. Führen Sie dazu den folgenden Befehl auf Ihrem Terminal aus:

npm laufen dev

Dieser Befehl startet einen Entwicklungsserver auf localhost: 3000. Folgen Sie dem Link auf Ihrem Terminal, um die Dokumentationsseite anzuzeigen. Die Homepage sollte so aussehen:

Wenn Sie auf der linken Seite der Seite nachsehen, finden Sie die genannten Seiten Einführung Und Eine andere Seite. Unterhalb dieser Seitenlinks finden Sie eine Seite namens Satori, eingebettet in die Erweitert (A-Ordner) Verzeichnis. Schließlich finden Sie im Navigationsbereich Links zu den Um Und Kontakt Seiten.

Um zu verstehen, wie diese Seiten funktionieren, müssen Sie zuerst verstehen wie Next.js Seiten rendert.

Verstehen der Verzeichnisstruktur

Da Nextra das Next.js-Framework verwendet, rendert es jede Datei in der Seiten/ Ordner als separate Seite.

Im Inneren des Seiten Verzeichnis finden Sie vier Vorlagendateien: über.mdx, advanced.mdx, eine andere.mdx, Und index.mdx. Jede dieser Dateien entspricht einer Seite der Website; Zum Beispiel, index.mdx entspricht der Startseite. Die URL localhost: 3000/ungefähr entspricht über.mdx, usw.

Innen Seiten, gibt es auch einen Ordner namens fortschrittlich, die eine einzelne Datei mit dem Namen enthält satori.mdx. Die URL für diese Datei lautet localhost: 3000/advanced/satori.

Beachten Sie, wie jede dieser Dateien mit a endet .mdx Verlängerung.

Was ist MDX?

Wenn Sie haben Erfahrungen mit React, sollten Sie JSX kennen. Dies ist eine HTML-ähnliche Sprache, mit der Sie die Benutzeroberfläche von React-Komponenten beschreiben können.

MDX lädt, analysiert und rendert JSX in einem Markdown-Dokument. Dank MDX können Sie React-Komponenten schreiben und bei Bedarf in Ihre Markdown-Dokumente importieren. MDX-Dateien enden mit der Erweiterung .mdx und können sowohl Markdown als auch JSX enthalten.

Mit MDX können Sie Ihr Markdown-Wissen mit React kombinieren, um wiederverwendbare Komponenten zu erstellen. Du kannst CSS-Module erstellen um die Komponenten zu stylen. Dies hilft Ihnen, Ihre Komponenten zu organisieren, um die Lesbarkeit und Wartbarkeit zu verbessern.

So bearbeiten Sie vorhandene Seiten in der Dokumentations-Site

Um eine bestehende Seite zu bearbeiten, öffnen Sie einfach die entsprechende Datei und nehmen Änderungen daran vor. Unterstützte Sprachen sind Markdown und JSX.

Öffnen Sie beispielsweise die index.mdx Datei und ersetzen Sie den Inhalt durch diesen:

# Willkommen zu meiner Dokumentation
Ich freue mich, Sie hier zu sehen. Danke
## Meine sozialen Netzwerke
Folge mir auf [Twitter](https://twitter.com/kingchuuks) Und [LinkedIn](https://linkedin.com/in/kingchuks)

In diesem Beispiel wird Markdown verwendet, um den Inhalt zu formatieren. Es enthält eine Überschrift der ersten Ebene, eine Überschrift der zweiten Ebene und zwei Links zu sozialen Medien.

Speichern Sie die Datei und besuchen Sie die Startseite Ihrer Dokumentationssite. Die Seite sollte nun so aussehen:

Unten auf der Seite finden Sie auch das Datum der letzten Aktualisierung des Dokuments.

Hinzufügen einer neuen Seite

Bevor Sie eine neue Seite hinzufügen, müssen Sie zunächst entscheiden, ob sich die Seite in der befinden soll Seiten/ Verzeichnis oder in einem Ordner darin. Verwenden Sie Ordner, wenn Sie Ihre Seiten kategorisieren oder eine Hierarchie entwickeln möchten.

Erstellen Sie in diesem Fall eine eigenständige Seite auf der obersten Ebene. Öffnen Sie eine Datei mit dem Namen installation.mdx in Ihrem Code-Editor und fügen Sie den folgenden Markdown-Code ein:

# Installationsanleitung
Befolgen Sie diese Anleitung, um mein Paket in Ihrem Projekt zu installieren
## 1. Installieren Sie Node.js
Um Node.js zu installieren, besuchen Sie die
[Node.js-Dokumentationsseite](https://nodejs.org/en/download)

Speichern Sie die Datei und überprüfen Sie den Browser. Sie finden das Installationsetikett im Seitenmenü. Wenn Sie auf den Link klicken, werden die Inhalte von installation.mdx rendert auf der Seite:

In der Datei _meta.json innerhalb des Seitenverzeichnisses können Sie das Label ändern und weitere Konfigurationen vornehmen. Um mehr darüber zu erfahren, lesen Sie die Dateien organisieren Abschnitt von Dokumentation von Nextra.

React-Komponenten verwenden

MDX-Dateien können JSX enthalten, die Sprache, die React verwendet. Sie können eine Komponente im Komponentenordner erstellen und sie in jedes der Dokumente auf Ihrer Website importieren.

Ein Beispiel dafür, wie Sie Komponenten in Markdown einbetten können, sehen Sie in der eine andere.mdx Datei:

## Komponente
importiere {useState} aus 'react'
Stile aus „../components/counters.module.css“ importieren
export const Counter = () => { 
 const [count, setCount] = useState (0); 
 zurückkehren( 

 setCount (count+1)} className={styles.counter}> 
 {count} Mal geklickt