Cara Menggunakan Nextra Docs dan Deploy ke Vercel: Panduan Lengkap

Jika Anda ingin membuat situs dokumentasi yang ramping, modern, dengan mudah, Nextra Docs adalah salah satu alat terbaik yang tersedia. Dibangun di atas Next.js, Nextra memungkinkan Anda menulis dokumentasi dalam Markdown atau MDX, menyesuaikan tampilan dan nuansa, dan menerapkannya dengan mudah—terutama di Vercel. Dalam artikel ini, kita akan membahas cara menyiapkan situs Nextra Docs dari nol dan menerapkannya ke Vercel secara gratis.

Apa Itu Nextra Docs? Sahabat Terbaik Pembuat Dokumen Anda

Nextra docs adalah framework berbasis Next.js yang membuat pembuatan situs dokumentasi menjadi sangat mudah. Ini semua tentang konten Markdown (atau MDX) dengan Tema Dokumen bawaan yang menyediakan navigasi, pencarian, dan daftar isi secara otomatis. Berikut adalah alasan mengapa nextra docs hebat:

• Kesederhanaan Markdown: Tulis dokumen dalam Markdown atau MDX untuk konten yang kaya dan interaktif.
• Keunggulan Tema Dokumen: Sidebar yang dibuat otomatis, bilah pencarian, dan tata letak responsif.
• Kekuatan Next.js: Memanfaatkan kecepatan Next.js, app router, dan integrasi Vercel.
• Dapat Disesuaikan: Sesuaikan tema, tambahkan komponen React, atau bangun tata letak kustom.
• Sumber Terbuka: Dengan 3.8K+ bintang GitHub, ini didorong komunitas dan gratis.

Pengguna memuji nextra docs karena "hasil akhir tanpa konfigurasi" dan penerapan di Vercel. Siap membangun situs Anda? Mari kita mulai!

Mengapa Menggunakan Nextra Docs dengan Vercel?

Nextra docs sempurna untuk developer, startup, atau proyek sumber terbuka yang membutuhkan dokumentasi tingkat profesional dengan cepat. Memasangkannya dengan Vercel—markas Next.js—berarti:

• Penerapan Tanpa Hambatan: Vercel secara otomatis mendeteksi proyek nextra docs untuk penerapan sekali klik.
• Kecepatan Luar Biasa: Generasi situs statis dan CDN untuk pemuatan halaman instan.
• Hosting Gratis: Tingkat gratis Vercel menangani sebagian besar proyek dengan domain kustom.
• Skalabilitas: Menangani lonjakan traffic tanpa masalah.

Saya menerapkan situs uji ke Vercel, dan situs itu tayang dalam waktu kurang dari 5 menit—sangat lancar!

Cara Menyiapkan Nextra Docs: Panduan Langkah demi Langkah

Mari kita buat situs nextra docs dari nol menggunakan app router Next.js. Ikuti, dan Anda akan memiliki situs lokal yang berjalan dalam waktu sekitar 20 menit!

1. Buat Proyek Next.js Baru

• Buka terminal Anda dan buat aplikasi Next.js:

npx create-next-app my-nextra-docs

• Selama pengaturan, pilih Yes untuk semua pertanyaan kecuali:
• "Would you like to customize the import alias (@/* by default)?" (pilih No atau preferensi Anda).
• "Would you like your code inside a src/ directory?" (pilih No atau Yes—Saya sarankan memilih No demi kesederhanaan).
• Navigasi ke folder proyek:

cd my-nextra-docs

2. Instal Dependensi Nextra Docs

Instal paket inti untuk nextra docs:

npm install next react react-dom nextra nextra-theme-docs

3. Perbarui Skrip package.json

Pastikan package.json menyertakan skrip ini (biasanya ditambahkan oleh create-next-app):

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

• Untuk mode dev yang lebih cepat, Anda bisa menambahkan Turbopack (opsional):

"dev": "next --turbopack"

• Uji pengaturannya:

npm run dev

Kunjungi http://localhost:3000 untuk mengonfirmasi aplikasi Next.js berfungsi.

Jelek:( Tapi, yah, ini berfungsi! Sekarang mari kita coba perbaiki ini.

4. Konfigurasi Nextra Docs

• Ganti nama next.config.ts menjadi next.config.mjs dan ganti isinya dengan:

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

• Jika Anda mendapatkan kesalahan tsconfig.json, IDE Anda (misalnya, VS Code) mungkin meminta untuk memperbaikinya secara otomatis. Jika tidak, buka tsconfig.json dan tambahkan "next.config.mjs" ke array include:

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. Siapkan Komponen MDX

• Buat mdx-components.js di root proyek:

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. Perbarui Tata Letak Aplikasi

• Ganti isi dari app/layout.tsx (atau src/app/layout.tsx jika Anda memilih src/):

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Tambahkan Halaman Dokumentasi

• Hapus app/page.tsx (atau src/app/page.tsx). Ini membuat aplikasi kita menampilkan error 404 di halaman beranda kita. Jangan khawatir, kita bisa mengatasinya!

• Buat folder resources di app (atau src/app):

/app/resources
  /page.mdx

• Tambahkan konten contoh ke app/resources/page.mdx:

Untuk tujuan pengujian, saya menambahkan:

# Resources

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favourite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Comand Line](https://github.co./jlevy/the-art-of-command-line)

Tapi kontennya tidak perlu rumit dan bisa sesederhana:

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site:)

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in

• Pengalihan di next.config.mjs memperbaiki error 404 dengan mengarahkan / ke /resources. Cukup refresh http://localhost:3000 untuk melihat halaman beranda nextra docs Anda—keren sekali kan!

Silakan - edit halaman ini, tambahkan halaman lain, dan coba semua fitur seperti mode gelap/terang. Kekuatan ada di tangan Anda, dan pilihannya tidak terbatas!

Menerapkan Nextra Docs ke Vercel

Sekarang, mari kita buat situs nextra docs Anda tayang di Vercel—sangat mudah karena Vercel dibangun untuk Next.js.

8. Push Kode Anda ke GitHub

• Inisialisasi repo Git:

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

• Buat repo baru di GitHub terlebih dahulu, ganti yourusername/your-repo dengan detail Anda.

9. Terapkan ke Vercel

• Buka vercel.com, daftar atau masuk.

• Klik New Project dan impor repo GitHub Anda.
• Vercel secara otomatis mendeteksi proyek nextra docs Anda (pengaturan Next.js berlaku).
• Klik Deploy. Dalam waktu sekitar 3 menit, situs Anda akan tayang di URL seperti https://my-nextra-docs.vercel.app.
• Saya menerapkan milik saya, dan pengaturan domain kustom sangat mudah!

Menyesuaikan Situs Nextra Docs Anda

Ingin membuat nextra docs Anda menonjol? Coba ini:

• Tambahkan Halaman: Letakkan lebih banyak file .mdx di /app atau subfolder seperti /resources.
• Penyesuaian Tema: Perbarui theme.config.js untuk warna, font, atau opsi sidebar (lihat nextra.site/docs).
• Komponen Kustom: Perluas mdx-components.js atau buat folder /components.
• Pengaturan Pencarian: Aktifkan pencarian Algolia melalui theme.config.js untuk pencarian teks lengkap.
• Kode Langsung: Tambahkan Sandpack atau react-live untuk playground kode interaktif.

Saya menambahkan komponen callout kustom ke dokumen saya—terlihat profesional dalam 10 menit!

Pemecahan Masalah dan Tips untuk Nextra Docs

• Error 404 masih ada? Pastikan pengalihan di next.config.mjs mengarah ke /resources.
• Error TS? Verifikasi tsconfig.json menyertakan next.config.mjs.
• Penerapan Vercel gagal? Periksa skrip package.json dan hapus cache Vercel.
• Kebingungan dengan app router? Nextra docs 4+ menggunakan app router Next.js; versi yang lebih lama mendukung pages router.
• Mau contoh? Kloning repo Nextra atau periksa nextra.site.
• Tips Kecepatan: Gunakan Turbopack (next --turbopack) untuk pengembangan lokal yang lebih cepat.

Mengapa Nextra Docs dan Vercel Adalah Pasangan Sempurna

Nextra docs membuat dokumentasi menyenangkan dengan kesederhanaan Markdown dan kecepatan Next.js. Penerapan sekali klik dan hosting gratis Vercel melengkapi kesepakatan. Tentu, app router mungkin membingungkan pemula Next.js, tetapi dokumentasi Nextra sangat bagus. Dibandingkan dengan Docusaurus, nextra docs terasa lebih ringan dan modern.

Siap meluncurkan dokumen Anda? Bangun situs nextra docs Anda dan terapkan ke Vercel—Saya tidak sabar melihat kreasi Anda! Dan pastikan untuk mencoba Apidog.