[Next.js] Nextra를 사용한 문서화

[Next.js] 문서화를 위한 Nextra를 설치 및 시작

Nextra는 Next.js를 기반으로 하는 프레임워크로 컨텐츠 중심의 웹사이트를 구축할 수 있다.

Next.js의 모든 기능과 Markdown 기반 컨텐츠를 쉽게 생성할 수 있는 추가 기능이 있다.

 

1. Next 프로젝트 설치

Next.js, React, Nextra 및 Nextra Docs Theme를 설치해야 한다.

먼저 프로젝트를 설치하고자 하는 디렉토리에서 아래 명령어를 실행하여 Next.js 프로젝트 폴더를 설치한다.

# npx 사용
npx create-next-app@latest "프로젝트 이름"

# pnpm 사용
pnpm create next-app "프로젝트 이름"

# yarn 사용
yarn create next-app "프로젝트 이름"

 

이후 아래와 같이 프로젝트 생성을할 때 타입스크립트, ESLint등을 사용할지 말지 지정해준다.

✔ Would you like to use TypeScript with this project? … No / Yes
✔ Would you like to use ESLint with this project? … No / Yes
✔ Would you like to use Tailwind CSS with this project? … No / Yes
✔ Would you like to use `src/` directory with this project? … No / Yes
✔ Use App Router (recommended)? … No / Yes
✔ Would you like to customize the default import alias? … No / Yes

* 이때 Nextra는 현재 App Router를 지원하지 않기 때문에 Use App Router항목을 No로 설정한다.

 

 

2. Nextra 패키지 추가

생성된 프로젝트 폴더로 들어가고 아래 명령어를 실행하여 Nextra Docs Theme를 설치한다.

# npm 사용
npm i nextra nextra-theme-docs

# pnpm 사용
pnpm i nextra nextra-theme-docs

# yarn 사용
yarn add nextra nextra-theme-docs

 

 

3. Next.config.js 설정

루트 디렉토리에 있는 next.config.js파일을 아래와 같이 설정한다.

/** @type {import('nextra').NextraConfig} */
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})
 
module.exports = withNextra()

 

다른 Next.js 구성이 있는 경우 매개 변수로 전달할 수 있다.

/** @type {import('nextra').NextraConfig} */
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};
module.exports = withNextra(nextConfig)

 

 

4. Nextra 테마 설정

루트디렉토리에 theme.config.jsx파일을 생성하고 아래와 같이 설정한다.

export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: 'https://github.com/shuding/nextra'
  }
  // ...
}

이 파일은 Nextra Docs테마를 구성하는 데 사용된다.

 

자세한 테마 구성요소는 아래에서 확인할 수 있다.

https://nextra.site/docs/docs-theme/theme-configuration

Theme Configuration – Nextra

 

 

5. Nextra 시작

1. create next-app 명령어로 설치되면서 nextra에 필요없는 폴더인 src/ 폴더를 삭제한다.

2. pages/index.mdx에 아래와 같은 코드를 입력하여 첫 번째 MDX페이지를 만들 수 있다.

# Welcome to Nextra
 
Hello, world!

 

이후 아래와 같은 명령어를 통해 프로젝트 개발을 시작할 수 있다.

# npm 사용
npm run dev

# pnpm 사용
pnpm dev

# yarn 사용
yarn dev

 

Nextra에 대한 자세한 애용은 공식홈페이지에서 확인할 수 있다.

https://nextra.site/

Nextra – Next.js Static Site Generator – Nextra