Blog

넥스트라 문서 사용법 및 Vercel 배포 방법: 단계별 가이드

Ashley Goolam

Ashley Goolam

12 June 2025

넥스트라 문서 사용법 및 Vercel 배포 방법: 단계별 가이드

쉽게 세련되고 현대적인 문서 웹사이트를 만들고 싶다면, Nextra Docs는 사용 가능한 최고의 도구 중 하나입니다. Next.js 기반으로 구축된 Nextra를 사용하면 문서를 Markdown 또는 MDX로 작성하고, 모양과 느낌을 사용자 정의하며, 특히 Vercel에 쉽게 배포할 수 있습니다. 이 글에서는 Nextra Docs 사이트를 처음부터 설정하고 Vercel에 무료로 배포하는 방법을 단계별로 살펴보겠습니다.

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하시나요?

개발팀이 최대한의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하시나요?

Apidog는 여러분의 모든 요구를 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
button

Nextra Docs란 무엇인가요? 당신의 문서 구축 절친

Nextra docs는 Next.js 기반의 프레임워크로, 문서 사이트를 쉽게 만들 수 있도록 해줍니다. 탐색, 검색, 목차 기능이 기본적으로 포함된 사전 구축된 Docs 테마와 함께 Markdown(또는 MDX) 콘텐츠에 중점을 둡니다. nextra docs가 훌륭한 이유는 다음과 같습니다.

사용자들은 nextra docs의 "제로 설정 깔끔함"과 Vercel 배포에 대해 극찬합니다. 사이트를 구축할 준비가 되셨나요? 시작해 봅시다!

왜 Vercel과 함께 Nextra Docs를 사용해야 할까요?

Nextra docs는 빠르게 전문가 수준의 문서가 필요한 개발자, 스타트업, 오픈 소스 프로젝트에 완벽합니다. Next.js의 본고장인 Vercel과 함께 사용하면 다음과 같은 이점이 있습니다.

저는 Vercel에 테스트 사이트를 배포했는데, 5분도 안 되어 라이브 상태가 되었습니다. 정말 부드러웠어요!

Nextra Docs 설정 방법: 단계별 가이드

Next.js의 앱 라우터를 사용하여 nextra docs 사이트를 처음부터 만들어 봅시다. 따라오시면 약 20분 안에 로컬 사이트를 실행할 수 있습니다!

1. 새 Next.js 프로젝트 생성

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

2. Nextra Docs 종속성 설치

nextra docs의 핵심 패키지를 설치합니다.

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

3. package.json 스크립트 업데이트

package.json에 다음 스크립트가 포함되어 있는지 확인합니다 (일반적으로 create-next-app에 의해 추가됩니다).

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

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

http://localhost:3000을 방문하여 Next.js 앱이 작동하는지 확인합니다.

next js home page

못생겼네요 :( 하지만 잘 작동합니다! 이제 이걸 고쳐봅시다.

4. 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. MDX 컴포넌트 설정

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

const themeComponents = getThemeComponents()

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

6. 앱 레이아웃 업데이트

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. 문서 페이지 추가

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

테스트 목적으로 저는 다음을 추가했습니다.

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

하지만 콘텐츠는 복잡할 필요 없이 다음과 같이 간단해도 됩니다.

# Getting Started

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

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

이 페이지를 편집하고, 더 많은 페이지를 추가하고, 다크/라이트 모드와 같은 모든 기능을 사용해 보세요. 이제 여러분의 손에 달려 있으며, 옵션은 무한합니다!

light and dark mode

Nextra Docs를 Vercel에 배포하기

이제 nextra docs 사이트를 Vercel에 라이브로 올려봅시다. Vercel은 Next.js를 위해 만들어졌기 때문에 매우 쉽습니다.

8. 코드를 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. Vercel에 배포

varcel

Nextra Docs 사이트 사용자 정의하기

nextra docs를 더 멋지게 만들고 싶으신가요? 다음을 시도해 보세요.

저는 문서에 사용자 정의 콜아웃 컴포넌트를 추가했는데, 10분 만에 전문가처럼 보였습니다!

Nextra Docs 문제 해결 및 팁

custom nextra documentation example

Nextra Docs와 Vercel이 완벽한 조합인 이유

Nextra docs는 Markdown의 단순성과 Next.js의 속도로 문서 작업을 즐겁게 만듭니다. Vercel의 원클릭 배포와 무료 호스팅은 이를 더욱 완벽하게 만듭니다. 물론 앱 라우터는 Next.js 초보자에게 혼란을 줄 수 있지만, Nextra 문서는 탄탄합니다. Docusaurus와 비교했을 때, nextra docs는 더 가볍고 현대적인 느낌입니다.

문서를 출시할 준비가 되셨나요? nextra docs 사이트를 구축하고 Vercel에 배포하세요. 여러분의 창작물을 보게 되어 기쁩니다! 그리고 Apidog도 꼭 확인해 보세요.

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하시나요?

개발팀이 최대한의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하시나요?

Apidog는 여러분의 모든 요구를 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드