Zbuduj witrynę z dokumentami za pomocą Next.js przy użyciu Nextra

Jeśli znasz Next.js, możesz z łatwością stworzyć witrynę z dokumentacją. Ramy Nextra dbają o najdrobniejsze szczegóły za Ciebie; wszystko, co musisz zrobić, to dodać treść Markdown lub HTML oraz dane YAML lub JSON.

Wykonaj te czynności, aby utworzyć witrynę z dokumentacją za pomocą Nextra, generatora witryn statycznych opartego na Next.js. Zainstalujesz i skonfigurujesz niezbędne zależności, a następnie nauczysz się dodawać nowe dokumenty i strony, pisać Markdown i dołączać komponenty React.

Wymagania dotyczące tworzenia witryny z dokumentami za pomocą Nextra

Zacznij od zainstalowania Node.js, jeśli jeszcze tego nie zrobiłeś. The najnowsza wersja Node.js jest dostarczany z npm, menedżerem pakietów węzłów, który będzie potrzebny do zainstalowania zależności dla tego projektu.

Oprócz Node.js musisz zainstalować Git. Potrzebujesz Git, aby wdrożyć witrynę na stronach GitHub, Netlify lub u innego dostawcy usług hostingowych. Będziesz także potrzebować zaawansowanego edytora kodu, takiego jak VS Code.

Instalacja Nextry

Możesz użyć A Szablon dokumentacji nextra aby uruchomić witrynę z dokumentacją. Uruchom wiersz polecenia i przejdź do katalogu, w którym chcesz skonfigurować projekt. Następnie uruchom następujące polecenie, aby uruchomić witrynę z dokumentacją:

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

To polecenie spowoduje rusztowanie aplikacji w bieżącym katalogu. Następnie uruchom następujące polecenie, aby zainstalować zależności:

cd nextra-docs-szablon
instalacja npm

Po zakończeniu instalacji uruchom aplikację. Zrób to, uruchamiając następujące polecenie na swoim terminalu:

npm uruchom dev

To polecenie uruchamia serwer programistyczny na localhost: 3000. Kliknij łącze na swoim terminalu, aby wyświetlić witrynę z dokumentacją. Strona główna powinna wyglądać tak:

Jeśli spojrzysz na lewą stronę strony, znajdziesz strony o nazwach Wstęp I Inna strona. Poniżej tych linków do stron znajdziesz stronę o nazwie Satori, zagnieżdżoną w pliku Zaawansowane (folder) informator. Wreszcie, w obszarze nawigacji znajdziesz linki do O I Kontakt strony.

Aby zrozumieć, jak działają te strony, musisz najpierw zrozumieć jak Next.js renderuje strony.

Zrozumienie struktury katalogów

Ponieważ Nextra używa frameworka Next.js, renderuje każdy plik w formacie strony/ folder jako oddzielną stronę.

W środku strony katalogu znajdziesz cztery pliki szablonów: o.mdx, zaawansowany.mdx, inny.mdx, I indeks.mdx. Każdy z tych plików odpowiada stronie w witrynie internetowej; Na przykład, indeks.mdx odpowiada stronie głównej. Adres URL lokalny host: 3000/około koresponduje z o.mdx, i tak dalej.

Wewnątrz strony, istnieje również folder o nazwie zaawansowany, zawierający pojedynczy plik o nazwie satori.mdx. Adres URL tego pliku będzie miał postać lokalny host: 3000/zaawansowany/satori.

Zwróć uwagę, że każdy z tych plików kończy się na a mdx rozszerzenie.

Co to jest MDX?

Jeśli masz doświadczenie z Reactem, powinieneś wiedzieć o JSX. Jest to język podobny do HTML, którego możesz użyć do opisania interfejsu użytkownika komponentów React.

MDX ładuje, analizuje i renderuje JSX w dokumencie Markdown. Dzięki MDX możesz pisać komponenty React i importować je do dokumentów Markdown w razie potrzeby. Pliki MDX kończą się rozszerzeniem .mdx i mogą zawierać zarówno Markdown, jak i JSX.

MDX pozwala łączyć wiedzę o Markdown z Reactem, aby tworzyć komponenty wielokrotnego użytku. Możesz tworzyć moduły CSS stylizować komponenty. Pomaga to uporządkować komponenty w celu poprawy czytelności i łatwości konserwacji.

Jak edytować istniejące strony w witrynie z dokumentacją

Aby edytować istniejącą stronę, po prostu otwórz odpowiedni plik i wprowadź w nim zmiany. Obsługiwane języki to Markdown i JSX.

Na przykład otwórz plik indeks.mdx plik i zastąp zawartość tym:

# Witaj w mojej dokumentacji
Cieszę się, że cię tu widzę. Dzięki
## Moje serwisy społecznościowe
Obserwuj mnie na [Świergot](https://twitter.com/kingchuuks) I [Linkedin](https://linkedin.com/in/kingchuks)

W tym przykładzie użyto języka Markdown do sformatowania zawartości. Zawiera nagłówek pierwszego poziomu, nagłówek drugiego poziomu i dwa linki do mediów społecznościowych.

Zapisz plik i odwiedź stronę główną swojej witryny z dokumentacją. Strona powinna teraz wyglądać tak:

Na dole strony możesz również znaleźć datę ostatniej aktualizacji dokumentu.

Dodanie nowej strony

Przed dodaniem nowej strony musisz najpierw zdecydować, czy strona będzie w formacie strony/ katalogu lub wewnątrz folderu w nim. Użyj folderów, jeśli chcesz kategoryzować swoje strony lub opracować hierarchię.

W takim przypadku utwórz samodzielną stronę na najwyższym poziomie. Otwórz plik o nazwie instalacja.mdx w swoim edytorze kodu i wklej do niego następujący kod Markdown:

# Instrukcja instalacji
Postępuj zgodnie z tym przewodnikiem, aby zainstalować mój pakiet w swoim projekcie
## 1. Zainstaluj Node.js
Aby zainstalować Node.js, odwiedź stronę
[Witryna z dokumentacją Node.js](https://nodejs.org/en/download)

Zapisz plik i sprawdź przeglądarkę. Etykietę instalacji znajdziesz w menu bocznym. Po kliknięciu w link zawartość instalacja.mdx rendery na stronie:

Możesz zmienić etykietę i przeprowadzić inne konfiguracje w pliku _meta.json w katalogu pages. Aby dowiedzieć się więcej na ten temat, zapoznaj się z Organizuj pliki Sekcja Dokumentacja firmy Nextra.

Korzystanie z komponentów React

Pliki MDX mogą zawierać JSX, który jest językiem używanym przez React. Możesz utworzyć komponent w folderze komponentów i zaimportować go do dowolnego dokumentu w swojej witrynie.

Możesz zobaczyć przykład, jak możesz osadzić komponenty w Markdown w inny.mdx plik:

## Część
zaimportuj {useState} z „reagowania”
importuj style z „../components/counters.module.css”
export const Licznik = () => { 
 const [licznik, setCount] = useState (0); 
 powrót( 

 setCount (count+1)} className={styles.counter}> 
 Kliknięto {count} razy