Docusaurus로 매뉴얼 만들기 #1 설치부터 첫 문서까지

프레임워크 Docusaurus Documentation Static Site
3 분 소요

문서를 처음 체계적으로 만들다 보면 거의 예외 없이 같은 문제를 만납니다. README 한 장으로는 감당이 안 되는 문서를 어디에 쌓을 것인가 하는 문제입니다. 노션은 외부 공개와 버전 관리가 번거롭고, 블로그 도구로 만들면 글이 시간순으로 나열될 뿐 레퍼런스로 쓰기 불편합니다. 그래서 많은 팀이 문서를 코드처럼 다루는 방식, 곧 Docs as Code로 옮겨 갑니다. 마크다운으로 쓰고, Git으로 관리하고, 정적 사이트로 배포하는 방식입니다.

이 시리즈는 그 첫 단추인 정적 사이트 생성기로 문서 사이트를 짓는 법을 다룹니다. 도구는 Docusaurus입니다. React로 만들어졌고, 마크다운 안에서 React 컴포넌트를 쓰는 MDX와 다국어, 버전 관리를 핵심 기능으로 내장한 것이 강점입니다. 설치는 Hugo나 MkDocs보다 무겁지만, 그만큼 확장성이 높습니다.

이번 시리즈는 Docusaurus로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지 ← 이번 글
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, admonition
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 Docusaurus가 무엇을 준비물로 요구하는지, 그리고 새 사이트를 만들어 개발 서버로 첫 문서를 띄우는 데까지를 직접 실행해 보며 마무리하겠습니다.

준비물 — Node.js #

Docusaurus는 Node.js 위에서 도는 도구입니다. 그래서 준비물은 Node.js 18 버전 이상입니다. 설치 후 버전을 확인합니다.

버전 확인 
node --version

Node를 설치하면 패키지 매니저 npm도 함께 깔립니다. Hugo가 단일 바이너리였고 MkDocs가 Python 패키지였던 것과 달리, Docusaurus는 자바스크립트 생태계 위에서 움직입니다.

새 사이트 만들기 #

생성기가 사이트의 뼈대를 한 번에 만들어 줍니다. classic 템플릿을 쓰면 문서, 블로그, 기본 테마가 모두 포함된 형태로 시작합니다.

새 사이트 생성 
npx create-docusaurus@latest my-docs classic

명령이 끝나면 my-docs 폴더 안에 필요한 파일이 모두 들어 있고, 의존성까지 설치된 상태가 됩니다.

첫 문서 띄우기 #

만들어진 폴더로 들어가 개발 서버를 띄웁니다.

개발 서버 실행 
cd my-docs
npm start

브라우저에서 http://localhost:3000이 자동으로 열리며, 기본 문서가 나타납니다. 파일을 고치면 화면이 즉시 갱신됩니다. 문서 본문은 docs 폴더에 들어 있고, 첫 화면은 docs/intro.md입니다. 이 파일을 열어 내용을 바꿔 보겠습니다.

docs/intro.md 
---
sidebar_position: 1
---

# 시작하기

우리 팀의 공식 문서입니다. 왼쪽 사이드바에서 항목을 골라 보세요.

sidebar_position은 사이드바에서의 순서입니다. 숫자가 작을수록 위에 옵니다.

폴더 구조 이해하기 #

생성된 구조에서 당장 알아야 할 곳은 몇 군데입니다.

폴더 구조 
my-docs/
├─ docusaurus.config.js   # 사이트 설정
├─ sidebars.js            # 사이드바 정의
├─ docs/                  # 문서 본문 (여기를 채웁니다)
│  └─ intro.md
├─ src/                   # 커스텀 페이지, React 컴포넌트
├─ static/                # 이미지 등 정적 파일
└─ build/                 # npm run build 산출물 (배포용)

문서를 늘리는 일은 docs 아래에 마크다운 파일을 더하는 일입니다. 다만 Hugo가 폴더 구조를 그대로 사이드바로 삼았던 것과 달리, Docusaurus는 sidebars.js로 사이드바를 정의합니다. 그 방법은 다음 편에서 본격적으로 다룹니다.

마무리 #

이번 글에서는 Node.js를 준비하고, create-docusaurus로 사이트를 생성해 개발 서버로 첫 문서를 띄우는 데까지 마쳤습니다. Docusaurus는 설치가 무거운 대신, 이미 React와 자바스크립트에 익숙한 팀이라면 가장 자연스럽게 손에 붙는 도구입니다.

다음 편에서는 사이드바와 검색을 다룹니다. 문서가 수십 편으로 늘어도 독자가 길을 잃지 않도록, sidebars.js로 정보 구조를 설계하는 단계입니다.

X