본문으로 건너뛰기

Docusaurus

v1
작성 2026-04-12읽는 시간 7분

문서 사이트를 레고 블록처럼 조립하기

이건 뭐예요?​

혹시 동네 도서관을 떠올려 보신 적 있나요. 책은 수천 권인데, 사서분이 장르별·주제별로 딱딱 정리해 두신 덕분에 우리는 그냥 들어가서 원하는 책을 쉽게 찾을 수 있잖아요. Docusaurus(도큐사우루스) 는 딱 그 사서 역할을 해주는 도구예요. 메타(예전 페이스북)라는 회사에서 만든 정적 사이트 생성기랍니다. 정적 사이트 생성기란 "글만 써두면 알아서 홈페이지로 만들어주는 프로그램" 이라고 이해하시면 돼요.

쉽게 말하면 이렇게 동작해요.

  • 여러분은 그냥 마크다운(.md) 파일 로 글만 써요. 마크다운은 # 기호로 제목을 표시하는 아주 쉬운 글쓰기 문법이에요
  • 폴더 안에 글 파일들을 차곡차곡 쌓아두면
  • Docusaurus가 그걸 읽어서 사이드바 메뉴, 검색창, 다크모드, 모바일 대응 까지 다 갖춘 멋진 사이트로 변환해줘요
  • 결과물은 그냥 HTML 파일이라 어디에나 올릴 수 있어요 (Vercel, Netlify, GitHub Pages 등)

블로그 플랫폼(워드프레스, 티스토리)이랑 다른 점은, 서버에 데이터베이스가 필요 없다는 점이에요. 그래서 빠르고, 깨질 일이 거의 없고, 공짜 호스팅도 많답니다.

우리는 이렇게 쓰고 있어요​

사실 지금 여러분이 보고 계신 이 사이트 ai.d-onworks.com 이 바로 Docusaurus로 만든 거예요. 어떻게 쓰고 있는지 실제 설정을 살짝 보여드릴게요.

1) 2단계 카테고리 폴더 구조​

docs/ 폴더 아래를 대분류 3개 + 각각 서브카테고리 구조로 나눠뒀어요. 그러면 글이 늘어나도 사이드바에서 찾기가 쉬워져요.

  • docs/lectures/ — LECTURES 강의 (VIBE CODING · PRESENTATION · TIPS)
  • docs/repos/ — REPOSITORIES 오픈소스 큐레이션 (FOUNDATION · AGENTS · MCP · DESIGN · QUALITY)
  • docs/skills/ — VIBE SKILLS 클로드 코드 노하우 (SETUP · WORKFLOW · MEMORY · INTEGRATIONS)

각 폴더마다 _category_.json 이라는 파일을 넣어서 카테고리 이름, 순서, 설명 을 지정해요. 예를 들어 docs/repos/foundation/_category_.json 에는 "FOUNDATION" 이라는 라벨과 "사이트·앱의 밑바탕이 되는 오픈소스들" 이라는 설명이 들어있어요. 그럼 사이드바에 딱 그 이름으로 나와요 (지금 이 글이 바로 거기 들어있답니다).

2) 사이드바는 자동 생성​

sidebars.js 파일(사이드바 메뉴를 정의하는 설정 파일)을 보면 핵심은 type: 'autogenerated' 한 줄이에요.

// sidebars.js 의 일부
archiveSidebar: [
  { type: 'autogenerated', dirName: '.' },
],

이게 뭐냐면, "docs/ 폴더 구조를 그대로 사이드바로 만들어줘" 라는 뜻이에요. 새 글을 docs/repos/ 안에 파일로 하나 추가하면 사이드바에 자동으로 등장해요. 일일이 메뉴 등록할 필요가 없어서 너무 편하답니다.

3) HOLOGRID 다크 테마​

docusaurus.config.js 에서 colorMode.defaultMode: 'dark' 로 설정해서 기본이 다크모드예요. 제가 개인적으로 시안 블루 계열의 HOLOGRID 라는 이름의 테마를 커스텀 CSS로 얹어서, 지금 이 푸른 빛의 홀로그램 같은 느낌이 나온답니다.

4) 한국어 기본 + 로컬 검색​

  • i18n.defaultLocale: 'ko' — 기본 언어를 한국어로 고정
  • @easyops-cn/docusaurus-search-local 플러그인으로 서버 없이 동작하는 풀텍스트 검색 (상단 돋보기 아이콘 눌러보세요, 한국어도 검색돼요)

5) 블로그는 꺼두고 아카이브만​

docusaurus.config.js 에서 blog: false 로 해뒀어요. 저희는 시간순 블로그가 아니라 주제별 아카이브가 목적이라서 그래요. 상단 메뉴도 "ARCHIVE", "GITHUB" 딱 두 개로 단순하게 유지했답니다.

한번 써볼까요?​

공식 설치는 정말 명령어 한 줄이에요. 아래 블록 오른쪽 상단의 복사 버튼(Docusaurus가 자동으로 붙여줘요)을 누르시면 돼요.

# Docusaurus 최신 버전으로 새 프로젝트 만들기 (classic 템플릿 사용)
npx create-docusaurus@latest my-website classic

여기서 my-website 는 여러분이 원하는 폴더 이름으로 바꾸시면 돼요. classic 은 기본 세트(문서, 블로그, 홈페이지, CSS 테마가 다 들어있는 패키지)를 뜻해요.

설치가 끝나면 개발 서버를 실행해서 바로 브라우저에서 확인할 수 있어요.

# 프로젝트 폴더로 이동
cd my-website

# 개발 서버 실행 (http://localhost:3000 에서 미리보기)
npm run start

배포용 정적 파일을 만들고 싶으시면 이 명령어예요.

# 프로덕션 빌드 (build 폴더에 HTML/CSS/JS가 생성됨)
npm run build

참고: npx 는 Node.js를 설치하시면 자동으로 같이 깔려요. Node.js가 없다면 먼저 nodejs.org 에서 LTS 버전을 설치하세요.

클로드 코드 터미널에서는 이렇게​

클로드 코드 터미널이 열려있다고 가정하고, 복사 → Enter 만 누르면 끝나는 순서대로 정리해 드릴게요. 한 줄씩 천천히 하셔도 되고, 전체를 한 번에 붙여넣으셔도 돼요.

# 1. 내가 프로젝트를 둘 폴더로 이동 (경로는 본인 환경에 맞게 수정)
#    윈도우라면 C:/src, 맥/리눅스라면 ~/src 처럼 쓰시면 돼요
cd C:/src

# 2. Docusaurus 새 사이트 만들기 — "my-site" 는 원하는 이름으로 바꿔도 돼요
npx create-docusaurus@latest my-site classic

# 3. 방금 만든 폴더로 들어가기
cd my-site

# 4. 개발 서버 띄우기 — 자동으로 브라우저가 열려요
npm run start

끝이에요. 4번 명령어까지 실행하면 브라우저에 http://localhost:3000 주소로 첫 화면이 뜰 거예요. 기본 샘플 사이트가 보이면 성공이랍니다.

확인 포인트: 왼쪽 사이드바에 "Tutorial - Basics" 같은 메뉴가 보이면 정상 설치된 거예요. 이제 docs/ 폴더 안에 여러분의 글을 .md 파일로 추가하면 바로 반영돼요 (개발 서버가 켜져 있으면 저장하자마자 화면이 자동 갱신돼요).

혹시 에러가 난다면 대부분 Node.js 버전 문제예요. 터미널에 node -v 를 쳐서 v18.0 이상이 뜨는지 먼저 확인해 주세요. 그보다 낮으면 nodejs.org 에서 LTS(장기 지원) 버전을 새로 설치하시면 돼요.

이런 분께 추천해요​

Docusaurus는 "데이터베이스 없이, 마크다운만으로, 꽤 괜찮은 사이트를 갖고 싶다" 는 분께 딱이에요. 특히 이런 세 분께 강력 추천드려요.

  1. 개인 브랜드 블로그를 시작하고 싶은 비개발자 — 워드프레스는 설치도 어렵고 매달 호스팅비도 나가잖아요. Docusaurus는 GitHub Pages나 Vercel로 공짜 배포가 가능하고, 글은 마크다운으로만 쓰면 되니까 글쓰기에만 집중할 수 있어요.

  2. 회사 제품 매뉴얼·지식베이스를 만들고 싶은 스타트업 대표 — 개발팀이 없어도 마크다운만 쓸 줄 알면 직원 누구나 글을 추가할 수 있고, GitHub에 올리면 버전 관리까지 자동이에요. 실제로 메타, Algolia, Redux, Jest 같은 유명 오픈소스 프로젝트들이 전부 Docusaurus로 문서를 만들고 있답니다.

  3. 학습 자료·AI 도구 노트를 정리하고 싶은 학생/연구자 — 스킬별로 폴더만 나눠 두면 사이드바가 자동으로 생기고, 검색도 바로 되니까 나중에 찾기도 쉬워요. AI//STUDY 사이트가 정확히 이 용도로 쓰고 있답니다.

참고 링크​

▸개정 이력1건
  • v12026-04-12초판

이 글이 도움이 되었나요?