Nextra — Next.js 문서 프레임워크은(는) 무엇을 하나요?
개요
귀하는 Nextra 전문가입니다. Nextra는 MDX 파일을 렌더링하고, 풀텍스트 검색, 다크 모드, i18n, 구문 강조를 내장한 Next.js 기반 문서 프레임워크입니다. 개발자가 React 컴포넌트를 마크다운에서 사용할 수 있는 문서 사이트, 블로그, 지식 베이스를 구축하도록 도와줍니다.
지침
설정
npx create-next-app my-docs --example https://github.com/shuding/nextra-docs-template
cd my-docs && npm run dev
# 또는 기존 Next.js 프로젝트에 추가
npm install nextra nextra-theme-docs
설정 파일
// next.config.mjs
import nextra from "nextra";
const withNextra = nextra({
theme: "nextra-theme-docs",
themeConfig: "./theme.config.tsx",
defaultShowCopyCode: true,
search: { codeblocks: true }, // 코드 블록 내 검색 활성화
});
export default withNextra({
reactStrictMode: true,
});
// theme.config.tsx
import { DocsThemeConfig } from "nextra-theme-docs";
const config: DocsThemeConfig = {
logo: <span style={{ fontWeight: 800 }}>My SDK</span>,
project: { link: "https://github.com/org/repo" },
chat: { link: "https://discord.gg/xxx" },
docsRepositoryBase: "https://github.com/org/repo/tree/main/docs",
footer: { text: "MIT License © 2026" },
useNextSeoProps() {
return { titleTemplate: "%s — My SDK Docs" };
},
head: (
<>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" href="/favicon.ico" />
</>
),
sidebar: { defaultMenuCollapseLevel: 1, toggleButton: true },
toc: { float: true, backToTop: true },
navigation: { prev: true, next: true },
};
export default config;
MDX 페이지
---
title: 시작하기
description: My SDK 빠른 시작 가이드
---
import { Callout, Tabs, Tab, Steps, Cards, Card, FileTree } from 'nextra/components'
# 시작하기
<Callout type="info">
이 가이드는 Node.js 18+이 설치되어 있다고 가정합니다.
</Callout>
## 설치
<Tabs items={['npm', 'yarn', 'pnpm']}>
<Tab>```bash npm install my-sdk ```</Tab>
<Tab>```bash yarn add my-sdk ```</Tab>
<Tab>```bash pnpm add my-sdk ```</Tab>
</Tabs>
## 빠른 시작
<Steps>
### SDK 설치
```bash
npm install my-sdk
클라이언트 초기화
import { SDK } from "my-sdk";
const client = new SDK({ apiKey: process.env.API_KEY });
첫 번째 요청 보내기
const users = await client.users.list();
console.log(users);
프로젝트 구조
관련 자료
자동 탐색
## 파일 기반 라우팅
pages/
index.mdx → /
getting-started.mdx → /getting-started
guide/
_meta.json → 사이드바 순서 및 레이블
installation.mdx → /guide/installation
configuration.mdx → /guide/configuration
api/
_meta.json
reference.mdx → /api/reference
## _meta.json — 사이드바 순서 제어
{
"installation": "설치",
"configuration": "설정",
"authentication": "인증",
"-- Separator": { "type": "separator", "title": "고급" },
"plugins": "플러그인",
"migration": "마이그레이션 가이드"
}
설치
npm install nextra nextra-theme-docs
예제
예제 1: 사용자가 nextra를 설정해 달라고 요청
사용자: "내 프로젝트에 nextra를 설정해줘"
에이전트는 다음을 수행해야 합니다:
- 시스템 요구 사항 및 전제 조건 확인
- nextra 설치 또는 설정
- 초기 프로젝트 구조 설정
- 설정이 올바르게 작동하는지 확인
예제 2: 사용자가 nextra로 기능을 구축해 달라고 요청
사용자: "nextra를 사용하여 대시보드를 만들어줘"
에이전트는 다음을 수행해야 합니다:
- 컴포넌트 또는 설정 스캐폴딩
- 적절한 데이터 소스에 연결
- 요청된 기능 구현
- 출력 테스트 및 검증
지침
- 대화형을 위한 MDX — 문서에서 React 컴포넌트(탭, 콜아웃, 대화형 예제)를 사용하세요. MDX가 이를 원활하게 만듭니다.
- 조직화를 위한 _meta.json —
_meta.json으로 사이드바 순서와 레이블을 제어하세요. 파일 이름 알파벳 순서에 의존하지 마세요. - 내장 검색 — Nextra는 FlexSearch 기반 풀텍스트 검색을 포함합니다. 소규모~중간 규모 사이트에는 Algolia 설정이 필요하지 않습니다.
- Next.js 기능 — SSR, ISR, API 라우트, 전체 Next.js 생태계를 사용할 수 있습니다. 대화형 문서에 유용합니다.
- 코드 블록 기능 — 코드 블록에서
defaultShowCopyCode, 파일명 레이블, 줄 강조를 활성화하세요. - 내장 다크 모드 — Nextra의 문서 테마에는 다크 모드 토글이 포함되어 있습니다. 모든 컴포넌트가 자동으로 적응합니다.
- i18n 지원 — 국제화를 내장 지원합니다. 동일한 구조로 로케일 폴더(en/, ja/, zh/)를 만드세요.
- Vercel에 배포 — 한 번의 클릭으로 배포합니다. 문서 변경 사항이 있는 모든 PR에 대해 자동 미리보기 배포를 제공합니다.