Docusaurus
문서 사이트를 레고 블록처럼 조립하기
이건 뭐예요?
혹시 동네 도서관을 떠올려 보신 적 있나요. 책은 수천 권인데, 사서분이 장르별·주제별로 딱딱 정리해 두신 덕분에 우리는 그냥 들어가서 원하는 책을 쉽게 찾을 수 있잖아요. 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는 "데이터베이스 없이, 마크다운만으로, 꽤 괜찮은 사이트를 갖고 싶다" 는 분께 딱이에요. 특히 이런 세 분께 강력 추천드려요.
-
개인 브랜드 블로그를 시작하고 싶은 비개발자 — 워드프레스는 설치도 어렵고 매달 호스팅비도 나가잖아요. Docusaurus는 GitHub Pages나 Vercel로 공짜 배포가 가능하고, 글은 마크다운으로만 쓰면 되니까 글쓰기에만 집중할 수 있어요.
-
회사 제품 매뉴얼·지식베이스를 만들고 싶은 스타트업 대표 — 개발팀이 없어도 마크다운만 쓸 줄 알면 직원 누구나 글을 추가할 수 있고, GitHub에 올리면 버전 관리까지 자동이에요. 실제로 메타, Algolia, Redux, Jest 같은 유명 오픈소스 프로젝트들이 전부 Docusaurus로 문서를 만들고 있답니다.
-
학습 자료·AI 도구 노트를 정리하고 싶은 학생/연구자 — 스킬별로 폴더만 나눠 두면 사이드바가 자동으로 생기고, 검색도 바로 되니까 나중에 찾기도 쉬워요. AI//STUDY 사이트가 정확히 이 용도로 쓰고 있답니다.
참고 링크
- 공식 사이트: docusaurus.io
- 공식 GitHub: facebook/docusaurus
- 공식 시작하기 가이드: docusaurus.io/docs
- 설치 가이드 원문: docusaurus.io/docs/installation
▸개정 이력1건
- v12026-04-12초판