Bangun Situs Doc Dengan Next.js Menggunakan Nextra

Jika Anda terbiasa dengan Next.js, Anda dapat menggunakannya untuk mengembangkan situs dokumentasi dengan mudah. Kerangka kerja Nextra menangani seluk-beluknya untuk Anda; yang harus Anda lakukan hanyalah menambahkan Markdown atau konten HTML dan data YAML atau JSON.

Ikuti langkah-langkah ini untuk membuat situs dokumentasi menggunakan Nextra, generator situs statis berbasis Next.js. Anda akan menginstal dan menyiapkan dependensi yang diperlukan, lalu mempelajari cara menambahkan dokumen dan halaman baru, menulis Markdown, dan menyertakan komponen React.

Persyaratan untuk Membangun Situs Doc Dengan Nextra

Mulailah dengan menginstal Node.js jika Anda belum melakukannya. Itu versi Node.js terbaru dilengkapi dengan npm, manajer paket node, yang Anda perlukan untuk menginstal dependensi untuk proyek ini.

Selain Node.js, Anda harus menginstal Git. Anda memerlukan Git untuk menerapkan situs ke halaman GitHub, Netlify, atau penyedia hosting lainnya. Anda juga memerlukan editor kode tingkat lanjut, seperti VS Code.

Menginstal Nextra

Anda dapat menggunakan a templat dokumen nextra untuk mem-bootstrap situs dokumentasi. Luncurkan prompt perintah dan arahkan ke direktori tempat Anda ingin menyiapkan proyek. Kemudian jalankan perintah berikut untuk mem-bootstrap situs dokumentasi:

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

Perintah ini akan membuat perancah aplikasi di dalam direktori saat ini. Selanjutnya, jalankan perintah berikut untuk menginstal dependensi:

cd nextra-docs-template
instal npm

Setelah instalasi selesai, mulai aplikasi. Lakukan dengan menjalankan perintah berikut di terminal Anda:

npm menjalankan dev

Perintah ini memulai server pengembangan di localhost: 3000. Ikuti tautan di terminal Anda untuk melihat situs dokumentasi. Beranda akan terlihat seperti ini:

Jika Anda melihat di sisi kiri halaman, Anda akan menemukan halaman bernama Perkenalan Dan Halaman lain. Di bawah tautan halaman ini, Anda akan menemukan halaman bernama Satori, bersarang di dalam Lanjutan (Folder) direktori. Terakhir, di area navigasi, Anda akan menemukan tautan ke Tentang Dan Kontak halaman.

Untuk memahami cara kerja halaman ini, Anda harus terlebih dahulu memahaminya bagaimana Next.js merender halaman.

Memahami Struktur Direktori

Karena Nextra menggunakan framework Next.js, Nextra merender setiap file dalam halaman/ folder sebagai halaman terpisah.

Di dalam halaman direktori, Anda akan menemukan empat file template: about.mdx, advanced.mdx, another.mdx, Dan index.mdx. Masing-masing file ini sesuai dengan halaman di situs web; Misalnya, index.mdx sesuai dengan halaman rumah. URL localhost: 3000/sekitar sesuai dengan about.mdx, dan seterusnya.

Di dalam halaman, ada juga folder bernama canggih, menampung satu file bernama satori.mdx. URL untuk file ini adalah localhost: 3000/advanced/satori.

Perhatikan bagaimana masing-masing file ini diakhiri dengan a .mdx perpanjangan.

Apa itu MDX?

kalau sudah pengalaman dengan Bereaksi, Anda harus tahu tentang JSX. Ini adalah bahasa mirip HTML yang dapat Anda gunakan untuk mendeskripsikan UI komponen React.

MDX memuat, mem-parsing, dan merender JSX dalam dokumen Markdown. Berkat MDX, Anda dapat menulis komponen React dan mengimpornya ke dalam dokumen Markdown Anda bila diperlukan. File MDX diakhiri dengan ekstensi .mdx dan dapat menyertakan Markdown dan JSX.

MDX memungkinkan Anda menggabungkan pengetahuan Anda tentang Markdown dengan React untuk membuat komponen yang dapat digunakan kembali. Kamu bisa membuat modul CSS untuk gaya komponen. Ini membantu Anda mengatur komponen untuk meningkatkan keterbacaan dan pemeliharaan.

Cara Mengedit Halaman yang Ada di Situs Dokumentasi

Untuk mengedit halaman yang ada, cukup buka file yang sesuai dan ubah. Bahasa yang didukung adalah Markdown dan JSX.

Misalnya, buka index.mdx file dan ganti konten dengan ini:

# Selamat Datang di Dokumentasi Saya
Saya senang melihat Anda di sini. Terima kasih
## Sosial Saya
Ikuti saya di [Twitter](https://twitter.com/kingchuuks) Dan [LinkedIn](https://linkedin.com/in/kingchuks)

Contoh ini menggunakan Markdown untuk memformat konten. Ini berisi tajuk tingkat satu, tajuk tingkat dua, dan dua tautan media sosial.

Simpan file dan kunjungi beranda situs dokumentasi Anda. Halaman sekarang akan terlihat seperti ini:

Di bagian bawah halaman, Anda juga dapat menemukan tanggal pembaruan terakhir dokumen.

Menambahkan Halaman Baru

Sebelum menambahkan halaman baru, Anda harus terlebih dahulu memutuskan apakah halaman tersebut akan berada di halaman/ direktori atau di dalam folder di dalamnya. Gunakan folder jika Anda ingin mengkategorikan halaman Anda atau mengembangkan hierarki.

Dalam hal ini, buat halaman mandiri di tingkat atas. Buka file bernama installation.mdx di editor kode Anda dan rekatkan kode Markdown berikut ke dalamnya:

# Petunjuk pemasangan
Ikuti panduan ini untuk menginstal paket saya di proyek Anda
## 1. Instal Node.js
Untuk menginstal Node.js, kunjungi
[Situs dokumentasi Node.js](https://nodejs.org/en/download)

Simpan file dan periksa browser. Anda akan menemukan label Instalasi di menu samping. Ketika Anda mengklik tautan, konten dari installation.mdx render di halaman:

Anda dapat mengubah label dan melakukan konfigurasi lain di file _meta.json di dalam direktori halaman. Untuk mempelajari lebih lanjut tentang ini, lihat Mengatur File bagian dari dokumentasi Nextra.

Menggunakan Komponen Bereaksi

File MDX dapat menyertakan JSX, yang merupakan bahasa yang digunakan React. Anda dapat membuat komponen di dalam folder komponen dan mengimpornya ke salah satu dokumen di situs Anda.

Anda dapat melihat contoh cara menyematkan komponen di Markdown di another.mdx mengajukan:

## Komponen
impor {useState} dari 'bereaksi'
impor gaya dari '../components/counters.module.css'
ekspor cons Counter = () => { 
 const [hitung, setCount] = useState (0); 
 kembali( 

 setCount (count+1)} className={styles.counter}> 
 Diklik {count} kali