오토프로그 — 노트북 앞의 개구리오토프로그
메뉴
자동화 솔루션
완제품 상품
교육
교육생라운지
랩스
소개
무료 진단
무료 진단
Repo 목차펼치기

Docusaurus

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

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

이건 뭐예요?

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

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

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

블로그 플랫폼(워드프레스, 티스토리)과 달리 서버에 데이터베이스가 필요 없어요. 빠르고, 깨질 일이 거의 없고, 무료 호스팅도 많아요.

우리는 이렇게 쓰고 있어요

지금 여러분이 보고 계신 이 사이트 autofrog.kr/lab 이 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 도구 노트를 정리하고 싶은 학생/연구자 — 스킬별로 폴더만 나눠 두면 사이드바가 자동으로 생기고, 검색도 바로 되니까 나중에 찾기도 쉬워요. 오토프로그 랩스도 이 용도로 쓰고 있어요.

참고 링크

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

이 글은 오토프로그(AutoFrog) 랩스에서 씁니다 — (주)디온웍스가 운영하는 AI 업무 자동화·바이브 코딩 교육 브랜드 · autofrog.kr