CTRL K

Nextra 완벽 가이드

Next.js 기반의 정적 사이트 생성 프레임워크

개요

Nextra는 Next.js를 기반으로 구축된 문서화 사이트 생성 프레임워크입니다. Markdown(MDX)으로 콘텐츠를 작성하면 자동으로 아름답고 기능적인 문서 사이트를 생성해줍니다.

이 가이드에서는 Nextra의 핵심 개념을 이해하고, 프로젝트를 직접 시작하는 방법까지 알아봅니다. Nextra를 사용하면 복잡한 설정 없이도 검색 기능, 다크모드, 반응형 디자인이 포함된 전문적인 문서 사이트를 빠르게 구축할 수 있습니다.

★ Insight ─────────────────────────────────────

Nextra의 핵심 가치: “설정보다 컨벤션” 철학으로 복잡한 문서 사이트 설정을 대폭 단순화
MDX의 강력함: 마크다운 단순성 + React 컴포넌트 유연성으로 인터랙티브한 문서 작성 가능
Next.js 생태계 통합: App Router, RSC, Server Actions 등 최신 Next.js 기능을 그대로 활용 ─────────────────────────────────────────────────

배경

왜 Nextra가 필요한가?

문서화 사이트를 만들 때 개발자들은 다음과 같은 문제에 직면합니다:

복잡한 설정: 검색, 네비게이션, 다크모드 등 기본 기능을 직접 구현해야 함
콘텐츠 관리의 어려움: HTML이나 JSX로 모든 페이지를 작성하면 유지보수가 힘듦
성능 최적화: SEO와 빌드 최적화를 수동으로 처리해야 함
일관성 유지: 여러 페이지에서 동일한 스타일과 레이아웃을 유지하기 어려움

Nextra는 이러한 문제들을 해결하면서도 Next.js의 강력한 기능(SSG, SSR, API Routes 등)을 그대로 활용할 수 있습니다.

등장 이전의 방식

이전에는 Docusaurus, VuePress, Jekyll 같은 도구들을 사용했습니다. 하지만:

리액트 생태계에 완전히 통합되지 않음
커스터마이징이 제한적
Next.js의 최신 기능을 활용할 수 없음

Nextra는 Next.js 13+의 App Router, React Server Components 같은 최신 기능을 문서화 사이트에서도 사용할 수 있게 해줍니다.

핵심 개념

1. MDX 기반 콘텐츠

Nextra는 MDX(Markdown + JSX)를 사용합니다. 일반 마크다운처럼 작성하되, 필요할 때 리액트 컴포넌트를 바로 삽입할 수 있습니다.


# 제목
 
일반 마크다운 콘텐츠를 작성합니다.
 
<Callout type="info">
  리액트 컴포넌트를 바로 사용할 수 있습니다!
</Callout>
 
```javascript
// 코드 블록도 자동으로 하이라이팅됩니다
const greeting = "Hello, Nextra!";
```

2. 파일 시스템 기반 라우팅

Next.js의 파일 시스템 라우팅을 그대로 사용합니다. pages/ 디렉토리 구조가 곧 사이트 구조입니다.


pages/
├── index.mdx           → /
├── getting-started.mdx → /getting-started
└── api/
    ├── introduction.mdx → /api/introduction
    └── reference.mdx    → /api/reference

3. 테마 시스템

Nextra는 두 가지 공식 테마를 제공합니다:

Docs Theme: 기술 문서용 (사이드바, 목차, 검색)
Blog Theme: 블로그용 (포스트 목록, 태그, RSS)

각 테마는 설정 파일(theme.config.jsx)로 쉽게 커스터마이징할 수 있습니다.

4. 메타데이터 관리

_meta.json 파일로 페이지 순서, 제목, 숨김 여부를 관리합니다:


{
  "index": "홈",
  "getting-started": "시작하기",
  "api": {
    "title": "API 레퍼런스",
    "type": "page"
  },
  "changelog": {
    "title": "변경 로그",
    "href": "/changelog"
  }
}

빠른 시작

사전 준비

Node.js 18 이상
npm, yarn, 또는 pnpm

1단계: 프로젝트 생성

새 Nextra 프로젝트를 생성하세요:


npx create-nextra-app my-docs

프로젝트 유형을 선택하라는 메시지가 나타나면 docs를 선택하세요.


? What type of template do you want to create?
  ❯ docs (Documentation site with sidebar)
    blog (Blog site with posts list)
    custom (Start from scratch)

2단계: 프로젝트 구조 확인

생성된 프로젝트 구조는 다음과 같습니다:


my-docs/
├── pages/
│   ├── _meta.json      # 페이지 메타데이터
│   ├── index.mdx       # 홈페이지
│   └── getting-started.mdx
├── theme.config.jsx    # 테마 설정
├── next.config.js      # Next.js 설정
└── package.json

3단계: 개발 서버 실행

개발 서버를 시작하세요:


cd my-docs
npm install
npm run dev

브라우저에서 http://localhost:3000을 열면 문서 사이트를 확인할 수 있습니다.

4단계: 콘텐츠 추가

pages/ 디렉토리에 새 MDX 파일을 생성하세요:


# pages/tutorial.mdx 파일 생성

pages/tutorial.mdx:


# 튜토리얼
 
이것은 새로운 페이지입니다.
 
## 섹션 1
 
콘텐츠를 마크다운으로 작성하세요.
 
```javascript
// 코드 예제
const example = "자동으로 하이라이팅됩니다";
```

pages/_meta.json에 페이지를 추가하세요:


{
  "index": "홈",
  "getting-started": "시작하기",
  "tutorial": "튜토리얼"
}

저장하면 사이드바에 “튜토리얼” 메뉴가 자동으로 나타납니다.

5단계: 테마 커스터마이징

theme.config.jsx에서 사이트 설정을 변경하세요:


export default {
  logo: <span>내 문서 사이트</span>,
  project: {
    link: 'https://github.com/myorg/myproject'
  },
  docsRepositoryBase: 'https://github.com/myorg/myproject/tree/main',
  footer: {
    text: '© 2025 내 회사. All rights reserved.'
  },
  useNextSeoProps() {
    return {
      titleTemplate: '%s – 내 문서'
    }
  }
}

★ Insight ─────────────────────────────────────

테마 설정의 유연성: theme.config.jsx 하나로 전역 설정을 관리하여 일관성 유지
SEO 최적화 내장: useNextSeoProps로 각 페이지의 메타 태그를 자동으로 생성
Git 통합: docsRepositoryBase 설정으로 “페이지 편집” 기능을 자동으로 제공 ─────────────────────────────────────────────────

주요 기능

1. 내장 검색

Nextra Docs 테마는 FlexSearch 기반 전체 텍스트 검색을 자동으로 제공합니다.

키보드 단축키: Cmd/Ctrl + K
설정 없이 즉시 사용 가능
모든 MDX 콘텐츠를 자동으로 인덱싱

검색을 비활성화하려면:


// theme.config.jsx
export default {
  search: {
    component: null // 검색 비활성화
  }
}

2. 다크모드

다크모드가 기본으로 포함되어 있으며, 사용자 설정을 로컬 스토리지에 저장합니다.


// theme.config.jsx
export default {
  darkMode: true, // 다크모드 토글 활성화
  nextThemes: {
    defaultTheme: 'dark' // 기본 테마 설정
  }
}

3. 목차(Table of Contents)

각 페이지의 헤딩을 자동으로 파싱하여 오른쪽에 목차를 생성합니다.


// theme.config.jsx
export default {
  toc: {
    title: '이 페이지에서',
    float: true,          // 스크롤 시 고정
    headingComponent: null // 커스텀 헤딩 컴포넌트
  }
}

4. 코드 하이라이팅

shiki 기반 코드 하이라이팅이 자동으로 적용됩니다.


```typescript {3-5}
function greet(name: string) {
  // 3-5번 줄이 하이라이팅됩니다
  console.log(`Hello, ${name}!`);
  return true;
}
```

지원 기능:

줄 번호 표시
특정 줄 하이라이팅
파일명 표시
코드 복사 버튼

5. 컴포넌트 임베딩

MDX에서 리액트 컴포넌트를 직접 사용할 수 있습니다.

내장 컴포넌트:


import { Callout, Steps, Tabs } from 'nextra/components'
 
<Callout type="warning">
  중요한 정보입니다!
</Callout>
 
<Steps>
### 단계 1
첫 번째 단계를 수행하세요.
 
### 단계 2
두 번째 단계를 수행하세요.
</Steps>
 
<Tabs items={['JavaScript', 'TypeScript']}>
  <Tabs.Tab>
    ```js
    const value = 42;
    ```
  </Tabs.Tab>
  <Tabs.Tab>
    ```ts
    const value: number = 42;
    ```
  </Tabs.Tab>
</Tabs>

커스텀 컴포넌트:


import MyComponent from '../components/MyComponent'
 
<MyComponent data={myData} />

고급 기능

1. 국제화 (i18n)

Next.js의 i18n 기능을 활용하여 다국어 문서를 지원합니다.

next.config.js:


module.exports = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})({
  i18n: {
    locales: ['ko', 'en', 'ja'],
    defaultLocale: 'ko'
  }
})

디렉토리 구조:


pages/
├── index.ko.mdx      # 한국어
├── index.en.mdx      # 영어
├── index.ja.mdx      # 일본어
└── _meta.ko.json     # 한국어 메타데이터

2. 리모트 콘텐츠

외부 Markdown 파일을 불러올 수 있습니다:


// pages/remote-doc.mdx
import { RemoteContent } from 'nextra/remote-content'
 
export default () => (
  <RemoteContent
    url="https://raw.githubusercontent.com/org/repo/main/README.md"
  />
)

3. 정적 이미지 최적화

Next.js Image 컴포넌트를 MDX에서 사용할 수 있습니다:


import Image from 'next/image'
 
<Image
  src="/images/diagram.png"
  alt="아키텍처 다이어그램"
  width={800}
  height={400}
/>

4. API Routes 통합

Next.js API Routes를 활용하여 동적 기능을 추가할 수 있습니다:


// pages/api/search.js
export default function handler(req, res) {
  const { query } = req.query;
  // 커스텀 검색 로직
  res.json({ results: [] });
}

★ Insight ─────────────────────────────────────

하이브리드 접근: 정적 문서 + 동적 API Routes로 문서 사이트에도 인터랙티브한 기능 추가 가능
이미지 최적ization: Next.js Image 컴포넌트로 자동 리사이징, 포맷 변환, 지연 로딩 처리
서버리스 통합: API Routes를 통해 외부 서비스와 연동하거나 동적 콘텐츠 제공 ─────────────────────────────────────────────────

배포

Vercel (권장)

Vercel에서 자동 배포가 가능합니다:

GitHub 저장소에 코드를 푸시합니다
Vercel에서 프로젝트를 Import합니다
자동으로 빌드 및 배포됩니다

빌드 명령어:


npm run build

정적 내보내기

완전한 정적 사이트로 내보내기:

next.config.js:


module.exports = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})({
  output: 'export',
  images: {
    unoptimized: true
  }
})

빌드 및 내보내기:


npm run build
# out/ 디렉토리에 정적 파일 생성됨

실제 사용 사례

1. 오픈소스 프로젝트 문서

예시: SWR, Tailwind CSS, Prisma 공식 문서

장점:

GitHub와 자연스러운 통합 (Edit on GitHub)
MDX로 인터랙티브한 예제 포함 가능
Vercel 무료 호스팅

2. 사내 기술 문서

예시: API 레퍼런스, 개발 가이드, 운영 매뉴얼

장점:

비공개 저장소에서도 동일하게 작동
인증이 필요한 경우 Next.js Middleware로 보호 가능
버전 관리와 변경 이력 추적 용이

3. 제품 문서

예시: SaaS 제품의 사용자 가이드

장점:

마케팅 사이트와 동일한 Next.js 프로젝트에 통합 가능
검색 엔진 최적화(SEO) 우수
다국어 지원으로 글로벌 고객 대응

장점과 한계

장점

✅ 빠른 시작: 설정 없이 즉시 사용 가능한 문서 사이트
✅ 풍부한 기능: 검색, 다크모드, i18n이 기본 제공
✅ 완벽한 Next.js 통합: Next.js의 모든 기능 활용 가능
✅ MDX 지원: 리액트 컴포넌트를 마크다운에 자유롭게 삽입
✅ 개발자 경험: Hot Reload, TypeScript 지원, 직관적인 API
✅ 확장성: 커스텀 컴포넌트와 테마로 자유롭게 확장

한계

⚠️ 학습 곡선: Next.js와 MDX에 대한 기본 이해 필요
⚠️ 빌드 시간: 페이지가 많아지면 빌드 시간 증가
⚠️ 테마 제한: 공식 테마 외에는 직접 구현해야 함
⚠️ 클라이언트 사이드 의존성: 완전한 정적 사이트보다는 약간 무거움

언제 사용하면 좋은가?

Nextra를 선택하세요:

Next.js/React 생태계에 익숙한 팀
문서에 인터랙티브한 요소가 필요한 경우
마케팅 사이트와 문서를 하나의 프로젝트로 관리하고 싶을 때
빠르게 프로토타입을 만들고 싶을 때

대안을 고려하세요:

매우 단순한 문서만 필요하다면: VitePress, DitePress, Docusaurus
Vue 생태계라면: VuePress
블로그 중심이라면: Astro, Gatsby
정적 사이트 성능이 최우선이라면: Astro

★ Insight ─────────────────────────────────────

프레임워크 선택 기준: 팀의 기술 스택, 프로젝트 요구사항, 확장성 필요성을 종합적으로 고려
점진적 마이그레이션: 기존 Next.js 프로젝트에 Nextra를 추가하여 문서화 영역을 확장 가능
커뮤니티 생태계: Vercel 팀이 직접 관리하여 안정적인 업데이트와 버그 수정 보장 ─────────────────────────────────────────────────

다음 단계

Nextra 사용법을 익혔다면:

테마 커스터마이징: theme.config.jsx에서 로고, 색상, 레이아웃 변경
컴포넌트 라이브러리 구축: 재사용 가능한 MDX 컴포넌트 작성
검색 개선: Algolia DocSearch 같은 외부 검색 엔진 통합
분석 추가: Google Analytics 또는 Vercel Analytics 설정
CI/CD 구축: GitHub Actions로 자동 배포 파이프라인 구성

버전 정보

작성일: 2025-01-01
Nextra 버전: 3.x
Next.js 호환: 14.x, 15.x
React 호환: 18.x+

2025•developjik

All content is licensed under CC BY-NC-SA 4.0 unless otherwise noted.

Nextra 완벽 가이드

개요

배경

왜 Nextra가 필요한가?

등장 이전의 방식

핵심 개념

1. MDX 기반 콘텐츠

2. 파일 시스템 기반 라우팅

3. 테마 시스템

4. 메타데이터 관리

빠른 시작

사전 준비

1단계: 프로젝트 생성

2단계: 프로젝트 구조 확인

3단계: 개발 서버 실행

4단계: 콘텐츠 추가

5단계: 테마 커스터마이징

주요 기능

1. 내장 검색

2. 다크모드

3. 목차(Table of Contents)

4. 코드 하이라이팅

5. 컴포넌트 임베딩

고급 기능

1. 국제화 (i18n)

2. 리모트 콘텐츠

3. 정적 이미지 최적화

4. API Routes 통합

배포

Vercel (권장)

정적 내보내기

실제 사용 사례

1. 오픈소스 프로젝트 문서

2. 사내 기술 문서

3. 제품 문서

장점과 한계

장점

한계

언제 사용하면 좋은가?

관련 리소스

공식 문서

예제 사이트

학습 자료

다음 단계

버전 정보

댓글