[3/7] Docusaurus로 Markdown 웹사이트 구성하기
이 글은 실제 Abulafium 구축 이력(2026-10-09 기준)을 바탕으로 다시 작성한 공개용 실습 매뉴얼입니다.
[실제 검증]은 구축 과정에서 성공을 확인한 상태,[재현 절차]는 이를 일반화한 실행 순서,[확인 필요]는 실제 소스·대시보드를 추가 확인해야 하는 사항입니다. 명령어의<USER>,<REPO_URL>등은 자신의 환경으로 변경하세요.
완성 목표
garden/에서 관리하는 Markdown을 사이트 빌드에 연결하고, Blog·Courses·Projects·Lectures 페이지가 로컬에서 정상 출력되는지 확인한다. 여기서 다루는 대상은 Docusaurus 3이다.
재현 범위: 실제 사이트의
abulafium-site/src/pages/index.tsx,docusaurus.config.ts,plugins/,worker/존재와 로컬 빌드·배포 구조는 확인됐다. 그러나 커스텀 플러그인 내부의 콘텐츠 수집 알고리즘과 정확한 모든 패키지 버전은 제공 자료만으로 검증되지 않았다. 아래에서는 실행 가능한 소스 점검·빌드·검증 절차를 제공하고, 없는 코드를 임의로 만들어 '실제 적용 코드'라고 하지 않는다.
1. 현재 사이트 구조 [구성 확인]
abulafium/
├── garden/
│ ├── blog/{insights,tech-notes,life-log}/
│ ├── courses/
│ ├── projects/
│ └── lectures/
└── abulafium-site/
├── docusaurus.config.ts
├── package.json
├── package-lock.json # 실제 존재 여부 확인
├── src/pages/index.tsx
├── plugins/ # 콘텐츠 연결 커스텀 구현
├── worker/
└── wrangler.jsonc
garden/이 abulafium-site/의 형제 디렉터리라는 점이 중요하다. Docusaurus 기본 템플릿의 docs/ 폴더만으로 실제 사이트를 설명할 수 없다.
2. 설치되어 있는 소스를 우선 확인 [재현 절차]
Set-Location C:\works\abulafium\abulafium-site
node --version
npm --version
Get-Content .\package.json
Get-Content .\docusaurus.config.ts
Get-ChildItem .\plugins
Get-Content .\wrangler.jsonc
Node 버전은 package.json의 engines 등으로 확인한다. 이미 있는 저장소에서 npx create-docusaurus로 프로젝트를 다시 생성하면 기존 커스텀 코드가 손상될 수 있으므로 하지 않는다.
3. 재현용 설치 및 로컬 검증
Set-Location C:\works\abulafium\abulafium-site
npm ci
npm run build
npm ci는 lockfile을 전제로 의존성을 재현하며, npm run build는 Markdown 구성과 front matter 문제를 확인한다. 로컬 개발 서버는 package.json의 스크립트를 확인한 뒤 일반적으로 아래처럼 실행한다.
npm run start
완료 조건: 빌드 성공, 홈페이지와 네 개 콘텐츠 영역의 정상 내비게이션, 공개하지 않은 노트의 URL 접근 불가를 확인한다. URL이 안 보이는 것과 접근 차단은 다르므로 직접 주소 접근도 점검한다.
4. 콘텐츠 연결을 확인하는 방법
Select-String -Path .\docusaurus.config.ts, .\plugins\* -Pattern 'garden','blog','courses','projects','lectures' -ErrorAction SilentlyContinue
이 명령은 검색 힌트다. 커스텀 플러그인이 중첩 디렉터리에 있으면 편집기 전체 검색을 사용한다. 실제 빌드 루트(abulafium-site/)에서 상위 ../garden을 참조하는 코드가 있는지 확인한다. 모듈이 특정 상대 경로를 전제하면 Cloudflare 빌드 루트 변경 시 콘텐츠가 누락될 수 있다.
5. Markdown front matter [실제 오류 경험 반영]
---
title: "Garden 동기화 설계"
slug: /tech-notes/garden-sync
date: 2026-10-09
description: "Obsidian과 Hermes를 연결하는 동기화 구조"
tags:
- syncthing
- obsidian
draft: false
---
실제 장애: description이 문자열이 아닌 값으로 읽혀 Docusaurus 빌드 실패가 발생했다. description은 YAML 문자열로 두고 빌드 결과를 확인한다. category, draft, unlisted, sidebar_position은 현재 사용하는 콘텐츠 플러그인에 따라 해석이 다르므로 실제 스키마 확인 후 적용한다.
6. 강의노트와 개인 노트의 공개 범위
- 공개 후보:
blog/,courses/,projects/, 선택된lectures/ - 공개를 피해야 하는 작업 영역:
inbox/,ideas/,memos/, 개인 연구 원고 등 - [확인 필요] 실제 과목별 암호, 수업 진행별 단계 공개, 별도 사이드바 격리는 초기 요구사항이었다. Worker 코드에서 접근 통제가 구현됐는지 확인 전까지 '접근 제한 완료'라고 적지 않는다.
- 'GitHub가 Private이므로 사이트도 Private'이라는 판단은 틀리다. 정적 산출물로 포함된 파일은 공개될 수 있다.
7. 시행착오와 진단
| 증상 | 점검 대상 | 조치 |
|---|---|---|
description 오류 | YAML front matter 형식 | 문자열 인용 및 문법 확인 |
| 문서가 빌드에 안 나옴 | plugins/, 콘텐츠 수집 경로 | garden 상대 경로와 입력 패턴 확인 |
| 공개하면 안 될 문서 노출 | 빌드 파일, Worker 라우팅 | 제외 규칙과 접근 제어 수정 후 재빌드 |
| 페이지 URL 변경 | slug, 커스텀 라우팅 | 빌드 전후 링크 점검 |