Blog

Hướng Dẫn Chi Tiết Cách Sử Dụng Nextra Docs và Triển Khai Lên Vercel

Ashley Goolam

Ashley Goolam

12 tháng 6 2025

Hướng Dẫn Chi Tiết Cách Sử Dụng Nextra Docs và Triển Khai Lên Vercel

Nếu bạn muốn tạo một trang web tài liệu hiện đại, đẹp mắt một cách dễ dàng, Nextra Docs là một trong những công cụ tốt nhất hiện có. Được xây dựng trên nền tảng Next.js, Nextra cho phép bạn viết tài liệu của mình bằng Markdown hoặc MDX, tùy chỉnh giao diện và triển khai dễ dàng—đặc biệt là trên Vercel. Trong bài viết này, chúng ta sẽ cùng nhau tìm hiểu cách thiết lập một trang web Nextra Docs từ đầu và triển khai nó lên Vercel miễn phí.

💡
Bạn muốn một công cụ Kiểm thử API tuyệt vời có thể tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, All-in-One để Nhóm phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn và thay thế Postman với mức giá phải chăng hơn nhiều!
nút

Nextra Docs là gì? Người bạn tốt nhất để xây dựng tài liệu của bạn

Nextra docs là một framework dựa trên Next.js giúp việc tạo trang web tài liệu trở nên dễ dàng. Tất cả xoay quanh nội dung Markdown (hoặc MDX) với một Docs Theme được xây dựng sẵn, tích hợp điều hướng, tìm kiếm và mục lục ngay từ đầu. Dưới đây là lý do tại sao nextra docs lại tuyệt vời:

Người dùng đánh giá cao nextra docs vì sự "hoàn thiện không cần cấu hình" và khả năng triển khai trên Vercel. Sẵn sàng xây dựng trang web của bạn chưa? Hãy bắt đầu thôi!

Tại sao nên sử dụng Nextra Docs với Vercel?

Nextra docs hoàn hảo cho các nhà phát triển, startup hoặc các dự án mã nguồn mở cần tài liệu chuyên nghiệp một cách nhanh chóng. Kết hợp nó với Vercel—sân nhà của Next.js—có nghĩa là:

Tôi đã triển khai một trang web thử nghiệm lên Vercel, và nó đã hoạt động chỉ trong vòng chưa đầy 5 phút—mượt mà như bơ!

Cách thiết lập Nextra Docs: Hướng dẫn từng bước

Hãy tạo một trang web nextra docs từ đầu bằng cách sử dụng app router của Next.js. Làm theo hướng dẫn, và bạn sẽ có một trang web chạy cục bộ trong khoảng 20 phút!

1. Tạo một dự án Next.js mới

npx create-next-app my-nextra-docs
next js project options
cd my-nextra-docs

2. Cài đặt các dependency của Nextra Docs

Cài đặt các gói cốt lõi cho nextra docs:

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

3. Cập nhật Scripts trong package.json

Đảm bảo package.json bao gồm các scripts sau (chúng thường được thêm bởi create-next-app):

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

"dev": "next --turbopack"
package.json
npm run dev

Truy cập http://localhost:3000 để xác nhận ứng dụng Next.js hoạt động.

next js home page

Xấu:( Nhưng dù sao thì nó cũng hoạt động! Bây giờ hãy thử khắc phục điều này.

4. Cấu hình Nextra Docs

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
      }
    ]
  }
})

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

5. Thiết lập MDX Components

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

const themeComponents = getThemeComponents()

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

6. Cập nhật App Layout

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. Thêm các trang tài liệu

home page 404 error message
/app/resources
  /page.mdx

Để kiểm tra, tôi đã thêm:

# 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)

Nhưng nội dung không cần phức tạp và có thể đơn giản như:

# Getting Started

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

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in
nextra home page

Hãy thử chỉnh sửa trang này, thêm nhiều trang hơn và khám phá tất cả các tính năng như chế độ sáng/tối. Sức mạnh nằm trong tay bạn, và các tùy chọn là vô tận!

light and dark mode

Triển khai Nextra Docs lên Vercel

Bây giờ, hãy đưa trang web nextra docs của bạn lên mạng trên Vercel—cực kỳ dễ dàng vì Vercel được xây dựng cho Next.js.

8. Đẩy code của bạn lên GitHub

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

9. Triển khai lên Vercel

varcel

Tùy chỉnh trang web Nextra Docs của bạn

Muốn làm cho trang web nextra docs của bạn nổi bật? Hãy thử những điều sau:

Tôi đã thêm một component callout tùy chỉnh vào tài liệu của mình—trông chuyên nghiệp chỉ trong 10 phút!

Khắc phục sự cố và Mẹo cho Nextra Docs

custom nextra documentation example

Tại sao Nextra Docs và Vercel là một cặp đôi hoàn hảo

Nextra docs giúp việc tạo tài liệu trở nên thú vị với sự đơn giản của Markdown và tốc độ của Next.js. Khả năng triển khai chỉ với một cú nhấp chuột và hosting miễn phí của Vercel là điểm cộng lớn. Chắc chắn, app router có thể gây khó khăn cho người mới dùng Next.js, nhưng tài liệu của Nextra rất đầy đủ. So với Docusaurus, nextra docs cảm giác nhẹ nhàng và hiện đại hơn.

Sẵn sàng ra mắt tài liệu của bạn chưa? Xây dựng trang web nextra docs của bạn và triển khai lên Vercel—tôi rất háo hức được thấy sản phẩm của bạn! Và chắc chắn hãy dùng thử Apidog.

💡
Bạn muốn một công cụ Kiểm thử API tuyệt vời có thể tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, All-in-One để Nhóm phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn và thay thế Postman với mức giá phải chăng hơn nhiều!
nút

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống