Docusaurus 블로그 구축기
공부하면서 알게 된 지식이나 삽질하면서 문제를 해결했던 방법들이 잊히는 게 아쉬워 글로 남겨야지 생각만 하다가 드디어 블로그를 개설하고 이렇게 첫 번째 포스트를 작성하게 되었습니다.
이 글에서는 Docusaurus를 이용해 블로그를 만든 여정을 공유하려 합니다.
어떤 플랫폼을 사용할까
블로그 운영을 결심한 후 가장 먼저 고민한 것은 바로 "어떤 플랫폼을 사용할까?"였습니다.
블로그 플랫폼은 국내에서 많이 사용하는 네이버 블로그와 티스토리부터, 워드프레스, 브런치, 미디엄, 벨로그, 깃허브 페이지 등 정말 다양합니다.
저는 기술 블로그를 목적으로 했기 때문에, 우선 마크다운과 코드 하이라이팅을 지원하지 않는 네이버 블로그, 브런치, 미디엄은 고려 대상에서 제외했습니다. (GitHub Gist 등을 이용해 가능하다지만 불편할 거 같았습니다.) 또한, 워드프레스는 유지 비용이 들기 때문에 제외하고, 티스토리, 깃허브 페이지, 벨로그 중에서 고민했습니다.
글을 꾸준히 작성하려면 티스토리나 벨로그처럼 접근성과 편의성이 높은 플랫폼이 적합할 것 같았지만, 직접 블로그를 구축해 보고 싶은 마음도 있었습니다.
고민 끝에 도전적인 게 더 끌렸고, 이왕 할 거면 제대로 해보자는 생각과 글쓰기를 습관화하겠다는 다짐으로 깃허브 페이지를 선택했습니다.
GitHub Pages를 선택한 이유
- 마크다운 및 코드 하이라이팅 지원
- 유지 비용 없이 무료로 운영 가능
- 편리함보다는 도전에 끌림
어떤 정적 사이트 생성기를 사용할까
예전에 깃허브 페이지를 구축해 본 적이 있었는데, 당시에는 깃허브 페이지하면 Jekyll이라, Jekyll밖에 없는 줄 알고 있었습니다... 이번에 블로그 구축을 위해 조사해 보니 Jekyll 외에도 Hugo, Docusaurus, Gatsby, Hexo 등 다양한 정적 사이트 생성기(Static Site Generator, SSG)가 있다는 것을 알게 되었습니다. 이것들을 JAM Stack을 활용한 SSG라 부르더군요.
JAM Stack이란
JAM Stack은 JavaScript, API, Markup(HTML/CSS)을 사용해 웹사이트를 구축하는 방법을 의미합니다.
JAM Stack 기반의 정적 사이트 생성기 목록은 여기에서 확인할 수 있습니다.
저는 최근에 웹 개발에서 많이 사용되는 Javascript + React 조합의 프레임워크를 다뤄보고 싶었습니다.
그래서 해당 조합 중 GitHub Stars 수가 많은 상위 3개 프레임워크인 Next.js, Docusaurus, Gatsby를 조사해 보았습니다.
- Next.js: 서버 사이드 렌더링과 정적 사이트 생성을 지원하는 풀스택 프레임워크
- Docusaurus: 문서화와 블로그 생성에 특화된 정적 사이트 생성기
- Gatsby: 빠르고 최적화된 정적 사이트 생성을 위한 프레임워크
저는 고민 끝에 Docusaurus를 선택했습니다.
Docusaurus를 선택한 이유
- 깔끔한 기본 레이아웃
- 기본 제공되는 레이아웃 디자인이 깔끔하고, 공식 홈페이지도 해당 UI로 구현이 되어 있어 참조하기에 용이하리라 생각했습니다.
- 활발한 유지보수 및 커뮤니티
- React를 개발한 Meta에서 만든 프로젝트이기 때문에 유지보수와 커뮤니티가 꾸준히 활발할 것으로 기대했습니다.
- 다양한 마크다운 지원
- MDX를 지원, 탭, 코드 블록 내 라인 하이라이팅 등 유용한 기능을 제공하고 있습니다.
Docusaurus 블로그 구축
이제 본격적으로 블로그를 구축하는 방법을 설명해 보겠습니다. Docusaurus 공식 사이트에서 자세한 문서를 확인할 수 있으며, 한국어도 지원하지만 아직 완벽하지는 않은 거 같습니다.
1. Node.js 및 Yarn 설치
Docusaurus를 사용하려면 먼저 Node.js가 필요합니다.
각 OS에 맞는 패키지 매니저를 이용해 node를 설치한 후,
node -v 명령어로 정상 설치 여부 및 설치 버전을 확인할 수 있습니다.
# Node.js 설치
## macOS
brew node install
## Ubuntu/Debian
sudo apt install nodejs npm -y
## CentOS
curl -SL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs
# Node.js 버전 확인
node -v
> v22.12.0
2025년 1월 기준으로, 공식 문서에서는 18.0 버전 이상의 Node.js를 요구하고 있습니다.
사이트 배포를 위해 yarn도 설치해 줍니다.
npm install --global yarn
2. Docusaurus 기본 템플릿 생성
Docusaurus에서 기본으로 제공하는 classic 템플릿을 이용해 웹사이트를 생성합니다.
여기서 my-website는 생성되는 폴더명이므로 자유롭게 설정해 주시면 됩니다.
npx create-docusaurus@latest my-website classic
실행 후 사용할 언어를 선택하는 옵션이 나오면, 방향키를 이용해 JavaScript 또는 TypeScript를 선택할 수 있습니다. 저는 TypeScript를 선택했습니다.
? Which language do you want to use? › - Use arrow-keys. Return to submit.
JavaScript
❯ TypeScript
참고로 아래와 같이 인자로 사용할 언어를 지정해 주는 것도 가능합니다.
npx create-docusaurus@latest my-website classic --typescript
명령이 성공적으로 실행됐다면, my-website 폴더에 아래와 같은 파일들이 생성됩니다.
my-website
├── README.md
├── blog
│ ├── 2019-05-28-first-blog-post.md
│ ├── 2019-05-29-long-blog-post.md
│ ├── 2021-08-01-mdx-blog-post.mdx
│ ├── 2021-08-26-welcome
│ │ ├── docusaurus-plushie-banner.jpeg
│ │ └── index.md
│ ├── authors.yml
│ └── tags.yml
├── docs
│ ├── intro.md
│ ├── tutorial-basics
│ │ ├── _category_.json
│ │ ├── congratulations.md
│ │ ├── create-a-blog-post.md
│ │ ├── create-a-document.md
│ │ ├── create-a-page.md
│ │ ├── deploy-your-site.md
│ │ └── markdown-features.mdx
│ └── tutorial-extras
│ ├── _category_.json
│ ├── img
│ │ ├── docsVersionDropdown.png
│ │ └── localeDropdown.png
│ ├── manage-docs-versions.md
│ └── translate-your-site.md
├── docusaurus.config.ts
├── package-lock.json
├── package.json
├── sidebars.ts
├── src
│ ├── components
│ │ └── HomepageFeatures
│ │ ├── index.tsx
│ │ └── styles.module.css
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── index.module.css
│ ├── index.tsx
│ └── markdown-page.md
├── static
│ └── img
│ ├── docusaurus-social-card.jpg
│ ├── docusaurus.png
│ ├── favicon.ico
│ ├── logo.svg
│ ├── undraw_docusaurus_mountain.svg
│ ├── undraw_docusaurus_react.svg
│ └── undraw_docusaurus_tree.svg
└── tsconfig.json
3. 로컬 개발 서버 실행
프로젝트 폴더 my-website로 이동한 후, npm run start 명령을 실행하면 로컬 개발 서버가 실행됩니다.
cd my-website
npm run start
기본적으로 http://localhost:3000/ 에서 사이트를 확인할 수 있으며, 설정이나 코드 변경 사항이 실시간으로 반영됩니다.
Classic 템플릿으로 만들어진 웹사이트는 아래와 같은 모습을 하고 있으며,
Docusaurus 공식 사이트와 유사한 것을 확인할 수 있습니다.
npm run 명령은 npm 스크립트를 실행할 때 사용하는 명령어로,
프로젝트의 package.json 파일에 정의된 사용자 지정 스크립트를 실행할 수 있도록 도와줍니다.
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
...
},
따라서, npm run start는 npx docusaurus start와 동일하게 동작합니다.
4. 웹사이트 빌드
위의 로컬 개발 서버 실행에서 사용한 npm run start 명령은 빌드 없이 서버를 실행하여 사이트를 보여줍니다.
Docusaurus는 정적 렌더링 방식을 사용하므로, 웹사이트를 배포하려면 정적 파일로 빌드가 필요합니다.
웹사이트에 게시할 파일을 빌드하기 위해 npm run build 명령을 실행합니다.
빌드가 완료되면 build 폴더 내에 정적 파일들이 생성됩니다.
이 build 폴더는 실제 배포를 위한 파일들로, 이를 웹 서버나 호스팅 서비스로 업로드해야 합니다.
예를 들어, GitHub Pages, Netlify, Vercel 등을 통해 웹사이트를 배포할 수 있습니다.
빌드된 결과물을 확인하려면 npm run serve 명령을 실행합니다.
이 명령을 실행하면 http://localhost:3000/ 에 빌드된 파일이 로드되며, 배포할 웹사이트를 미리 테스트할 수 있습니다.
5. GitHub Pages로 배포
이제 빌드한 웹사이트를 GitHub Pages에 배포해 보겠습니다.
우선 GitHub에서 [username].github.io라는 이름으로 public 레포지토리를 생성합니다.
그리고 docusaurus.config.ts 파일에서 아래 설정값을 수정 및 추가해 줍니다.
organizationName: 배포할 레포지토리를 소유하고 있는 GitHub 사용자 또는 그룹 계정을 설정합니다.projectName: 배포할 레포지토리 이름을 설정합니다.deploymentBranch: 배포할 브랜치 이름을 설정합니다. 일반적으로gh-pages브랜치를 많이 사용하지만, 임의로 설정해도 무방합니다.
const config: Config = {
...
url: 'https://[username].github.io',
baseUrl: '/',
organizationName: '[username]',
projectName: '[username].github.io',
deploymentBranch: 'gh-pages',
...
다음으로 아래 명령을 실행해 사이트를 GitHub Pages로 배포합니다. 명령이 실행되면 위에서 설정한 레포지토리의 브랜치에 빌드된 파일이 커밋된 것을 확인할 수 있습니다.
USE_SSH=true yarn deploy
마지막으로, 레포지토리의 Settings > Pages에 들어간 후, Build and deployment 항목에서 Branch를 배포에 사용할 브랜치로 변경해 줍니다.
이제 https://[username].github.io 에서 나만의 웹사이트를 확인하실 수 있습니다.
참고 사이트
- 공식 사이트: https://docusaurus.io
- Docusaurus 설치 가이드: https://docusaurus.io/docs/installation
- Docusaurus 배포 가이드: https://docusaurus.io/docs/deployment
다음 포스트는 Docusaurus 블로그를 커스터마이징하는 방법으로 찾아오겠습니다.