Next.js에 익숙하다면 이를 사용하여 기술 문서 사이트(Documentation)를 쉽게 개발할 수 있습니다. Nextra 프레임워크가 핵심적인 부분을 자동으로 처리하므로 마크다운 또는 HTML 콘텐츠와 YAML 또는 JSON 데이터를 추가하기만 하면 됩니다.
Next.js 기반 정적 사이트 생성기인 Nextra를 사용하여 기술 문서 사이트를 구축하는 단계를 안내합니다. 필요한 종속성을 설치하고 설정한 다음 새 문서와 페이지를 추가하고, 마크다운을 작성하고, React 컴포넌트를 포함하는 방법을 배웁니다.
Nextra로 문서 사이트를 구축하기 위한 요구 사항
아직 설치하지 않았다면 Node.js를 설치하는 것부터 시작하세요. 최신 Node.js 버전 에는 이 프로젝트의 종속성을 설치하는 데 필요한 노드 패키지 관리자 npm이 함께 제공됩니다.
Node.js 외에도 Git 을 설치해야 합니다. 사이트를 GitHub 페이지, Netlify 또는 다른 호스팅 제공업체에 배포하려면 Git이 필요합니다. 또한 VS Code와 같은 고급 코드 편집기가 필요합니다.
Nextra 설치
다음 문서 템플릿 를 사용하여 문서 사이트를 부트스트랩할 수 있습니다. 명령 프롬프트를 실행하고 프로젝트를 설정하려는 디렉토리로 이동합니다. 그런 다음 다음 명령을 실행하여 문서 사이트를 부트스트랩합니다:
git clone https://github.com/shuding/nextra-docs-template
이 명령은 현재 디렉터리 내에 애플리케이션을 스캐폴딩합니다. 그런 다음 다음 명령을 실행하여 종속 요소를 설치합니다:
cd nextra-docs-template
npm install
설치가 완료되면 애플리케이션을 시작합니다. 터미널에서 다음 명령을 실행하여 애플리케이션을 시작합니다:
npm run dev
이 명령은 로컬 호스트에서 개발 서버를 시작합니다:터미널의 링크를 따라가면 문서 사이트를 볼 수 있습니다. 홈페이지는 다음과 같이 표시됩니다:
페이지 왼쪽을 보면 소개 및 기타 페이지라는 이름의 페이지를 찾을 수 있습니다. 이 페이지 링크 아래에는 고급(A 폴더) 디렉터리 안에 중첩된 Satori라는 페이지가 있습니다. 마지막으로 탐색 영역에서 정보 및 연락처 페이지로 연결되는 링크를 찾을 수 있습니다.
이러한 페이지의 작동 방식을 이해하려면 먼저 Next.js가 페이지를 렌더링하는 방식을 이해해야 합니다.
디렉토리 구조 이해
Nextra는 Next.js 프레임워크를 사용하기 때문에 페이지/폴더에 있는 각 파일을 별도의 페이지로 렌더링합니다.
pages 디렉토리 안에는 about.mdx, advanced.mdx, another.mdx, index.mdx의 네 가지 템플릿 파일이 있습니다. 이러한 각 파일은 웹사이트의 페이지에 해당합니다(예: index.mdx는 홈 페이지에 해당). localhost:3000/about URL은 about.mdx 등에 해당합니다.
페이지 내부에는 고급이라는 이름의 폴더가 있으며, 이 폴더에는 satori.mdx라는 단일 파일이 들어 있습니다. 이 파일의 URL은 localhost:3000/advanced/satori입니다.
이러한 각 파일의 확장자가 .mdx로 끝나는 것을 주목하세요.
MDX란 무엇인가요?
React를 사용해 본 경험이 있다면 JSX에 대해 알고 있을 것입니다. 이것은 React 컴포넌트의 UI를 설명하는 데 사용할 수 있는 HTML과 유사한 언어입니다.
MDX는 마크다운 문서에서 JSX를 로드, 파싱, 렌더링합니다. MDX 덕분에 React 컴포넌트를 작성하고 필요할 때 마크다운 문서로 가져올 수 있습니다. MDX 파일은 확장자가 .mdx로 끝나며, 마크다운과 JSX를 모두 포함할 수 있습니다.
MDX를 사용하면 마크다운에 대한 지식과 React를 결합하여 재사용 가능한 컴포넌트를 만들 수 있습니다. 컴포넌트의 스타일을 지정하는 CSS 모듈을 생성할 수 있습니다. 이를 통해 컴포넌트를 구성하여 가독성과 유지보수성을 개선할 수 있습니다.
문서 사이트에서 기존 페이지를 편집하는 방법
기존 페이지를 편집하려면 해당 파일을 열고 변경하기만 하면 됩니다. 지원되는 언어는 마크다운과 JSX입니다.
예를 들어 index.mdx 파일을 열고 콘텐츠를 다음과 같이 바꿉니다:
# Welcome To My Documentation
I'm happy to see you here. Thanks
## My Socials
Follow me on [Twitter](https://twitter.com/kingchuuks) and [LinkedIn](https://linkedin.com/in/kingchuks)
이 예에서는 마크다운을 사용하여 콘텐츠의 형식을 지정합니다. 여기에는 레벨 1 제목, 레벨 2 제목 및 두 개의 소셜 미디어 링크가 포함되어 있습니다.
파일을 저장하고 문서 사이트의 홈페이지를 방문합니다. 이제 페이지가 다음과 같이 표시됩니다:
페이지 하단에서 문서의 마지막 업데이트 날짜도 확인할 수 있습니다.
새 페이지 추가
새 페이지를 추가하기 전에 먼저 페이지를 페이지/디렉토리에 넣을지 아니면 그 안에 있는 폴더에 넣을지 결정해야 합니다. 페이지를 분류하거나 계층 구조를 개발하려면 폴더를 사용하세요.
이 경우 최상위 레벨에 독립형 페이지를 만듭니다. 코드 편집기에서 installation.mdx라는 파일을 열고 다음 마크다운 코드를 붙여넣습니다:
# Installation Guide
Follow this guide to install my package in your project
## Install Node.js
To install Node.js, visit the
[Node.js documentation site](https://nodejs.org/en/download)
파일을 저장하고 브라우저를 확인합니다. 사이드 메뉴에서 설치 레이블을 찾을 수 있습니다. 링크를 클릭하면 설치.mdx의 콘텐츠가 페이지에 렌더링됩니다:
페이지 디렉터리 내의 _meta.json 파일에서 레이블을 변경하고 다른 구성을 수행할 수 있습니다. 이에 대한 자세한 내용은 Nextra 문서의 파일 구성 섹션을 참조하세요.
React 컴포넌트 사용하기
MDX 파일에는 React가 사용하는 언어인 JSX가 포함될 수 있습니다. 컴포넌트 폴더 내에서 컴포넌트를 생성하고 사이트의 모든 문서에서 가져올 수 있습니다.
다른.mdx 파일에서 Markdown에 컴포넌트를 임베드하는 방법의 예를 볼 수 있습니다:
## Component
import {useState} from 'react'
import styles from '../components/counters.module.css'
export const Counter = () => {
const [count, setCount] = useState(0);
return(
<div>
<button onClick={() => setCount(count+1)} className={styles.counter}>
Clicked {count} times
</button>
</div>
)
}
<Counter />
## External Components
import Counters from '../components/counters'
<Counters />
이 마크다운 파일에는 카운터 컴포넌트에 대한 정의가 포함되어 있습니다. 그런 다음 구성 요소 디렉토리에서 카운터 구성 요소를 가져옵니다.
문서 사이트 전체에서 동일한 컴포넌트를 사용하려면 독립형 컴포넌트로 만든 다음 필요할 때 가져오는 것이 가장 좋습니다.
마크다운에 대해 자세히 알아보기
기술 문서 사이트용 콘텐츠를 만들려면 마크다운 사용법을 알아야 합니다. 좋은 소식은 마크다운 구문은 매우 쉽게 익힐 수 있다는 것입니다. 마크다운에 대한 지식과 React를 결합하면 정말 강력한 기술 문서 사이트를 만들 수 있습니다.