공부한 내용, 업무 매뉴얼, 환경 셋업 기록을 한곳에 모아 두는 개인 위키.
마크다운 파일만 추가하면 사이드바·검색·태그·최근 목록이 알아서 따라오고, main에 push하면 자동으로 배포된다.
🔗 https://kangzzy.github.io/wiki-template/
VitePress · GitHub Pages · Dev Container
| 기능 | 설명 |
|---|---|
| 자동 사이드바 | docs/ 아래 폴더 구조를 그대로 사이드바·상단 메뉴로. 모든 카테고리가 항상 좌측에 보이고(현재 카테고리만 펼침), 설정 파일을 손댈 일이 없다 |
| 한국어 검색 | 한글을 bigram으로 색인해 설치로 설치하는을 찾는다 |
| 카테고리 카드 | 폴더를 만들면 홈에 카드가 자동 생성 |
| 태그 인덱스 | frontmatter의 tags를 모아 카테고리를 가로지르는 탐색 |
| 최근 업데이트 | 홈에 최근 수정 문서 10개. 날짜는 frontmatter 또는 git 커밋 시각 |
| Mermaid | ```mermaid 코드블록이 다이어그램으로 |
| 컴포넌트 자동 등록 | theme/components/에 .vue를 넣으면 어느 문서에서든 <MyThing /> |
| 다크 모드 | 기본 제공 |
VS Code에서 이 폴더를 열고 명령 팔레트 → Dev Containers: Reopen in Container.
Node 24 컨테이너가 뜨고 의존성 설치와 확장 설치까지 자동으로 끝난다.
npm run docs:devNode 20 이상이면 된다.
npm install && npm run docs:dev브라우저에서 http://localhost:5173/wiki-template/ 로 접속한다.
| 명령 | 하는 일 |
|---|---|
npm run docs:dev |
개발 서버 |
npm run docs:build |
프로덕션 빌드 (깨진 내부 링크가 있으면 실패한다) |
npm run docs:preview |
빌드 결과 미리보기 |
npm run new |
새 문서 만들기 |
VS Code에서는 명령 팔레트 → Tasks: Run Task 로 위 셋을 바로 실행할 수 있다.
npm run new카테고리를 고르고(없으면 그 자리에서 만들고), 템플릿을 고르고, 제목을 넣으면 끝이다.
📝 새 위키 문서 만들기
어느 카테고리에 넣을까요?
1. 개발 학습 노트 (dev/)
2. + 새 카테고리 만들기
번호 선택 (1-2): 1
어떤 템플릿으로 시작할까요?
1. 학습 노트 배운 것 / 개념 / 코드 예제 / 헷갈렸던 점
2. 매뉴얼 · 절차서 목적 / 사전 준비 / 절차 / 확인 방법
3. 셋업 가이드 환경 / 설치 / 설정 / 검증 / 트러블슈팅
번호 선택 (1-3): 1
문서 제목: VitePress 데이터 로더
파일명 (엔터 = vitepress): vitepress-data-loader
✔ 문서 생성: docs/dev/vitepress-data-loader.md
+ 새 카테고리 만들기를 고르면 폴더명·표시 제목·설명·아이콘을 물어보고 docs/<폴더>/index.md까지 만들어 준다.
참고 — 새 문서·카테고리를 사이드바와 상단 메뉴에 반영하려면 dev 서버를 다시 시작해야 한다. 사이드바는 설정을 읽을 때 한 번 계산되기 때문이다. 홈의 카테고리 카드·태그·최근 목록은 저장 즉시 갱신된다.
npm run new 없이 손으로 만들어도 된다. 카테고리 = docs/ 바로 아래 폴더 하나이고, 그 폴더의 index.md가 표지다.
-
docs/아래에 영문 소문자 폴더를 만든다. 예:docs/study/ -
그 안에
index.md를 만들고 표지 frontmatter를 넣는다.--- title: 학습 자료 # 홈 카드 제목 / 사이드바 그룹명 description: 강의·책 정리 icon: 📚 # 홈 카드 아이콘 (선택) order: 30 # 작을수록 앞 (선택) hidden: false # true면 홈·사이드바에서 숨김 (선택) --- # 학습 자료 이 카테고리 소개.
templates/category-index.md를 복사해 쓰면 편하다. -
문서를 추가한다.
docs/study/안에 아무.md나 만들고 frontmatter를 채우면 된다. 그 폴더의index.md는 사이드바 항목 목록에서는 빠지고 그룹 자체의 링크로 쓰인다. -
dev 서버를 다시 시작하면 홈 카드·사이드바·상단 메뉴에 자동으로 나타난다.
index.md없이 문서만 넣어도 폴더명이 그대로 카테고리 제목이 되어 동작한다. 다만 홈 카드 아이콘·설명·정렬을 주려면index.md가 있어야 한다.
templates/ 에 있다. 카테고리에 묶여 있지 않아 어디서든 원하는 걸 고르면 된다.
| 템플릿 | 언제 쓰나 | 뼈대 |
|---|---|---|
| 학습 노트 | 새로 공부한 기술을 정리할 때 | 배운 것 · 핵심 개념 · 코드 예제 · 헷갈렸던 점 · 참고 링크 |
| 매뉴얼 · 절차서 | 남(또는 미래의 나)이 그대로 따라 해야 할 때 | 목적·대상 · 사전 준비 · 절차 · 확인 방법 · 문제 발생 시 |
| 셋업 가이드 | 설치·환경 구축 과정을 남길 때 | 환경 정보 · 설치 · 설정 · 검증 · 트러블슈팅 |
내용이 마음에 안 들면 templates/*.md를 직접 고치면 된다. 다음부터 그 뼈대로 생성된다.
문서 맨 위 --- 블록이 모든 자동화의 입력값이다.
---
title: 문서 제목
description: 한 줄 요약
tags: [vitepress, 셋업]
created: 2026-07-24
updated: 2026-07-24
status: draft
order: 10
---| 필드 | 필수 | 하는 일 |
|---|---|---|
title |
권장 | 사이드바·검색·목록에 표시. 없으면 첫 # 헤딩, 그것도 없으면 파일명 |
description |
태그·최근 목록에 부연 설명으로 | |
tags |
/tags 페이지에 모임. 한글 태그도 된다 |
|
created |
기록용 | |
updated |
최근 목록의 정렬 기준. 비워 두면 git 커밋 시각을 쓴다 | |
status |
draft / wip / done — 본인 기억용 |
|
order |
작을수록 사이드바 위쪽. 없으면 제목 가나다순 |
카테고리 표지(docs/<폴더>/index.md)는 두 필드를 더 쓴다.
| 필드 | 하는 일 |
|---|---|
icon |
홈 카드에 표시할 이모지 |
hidden |
true면 홈 카드와 사이드바에서 통째로 숨김 |
문서를 편집하다 스크린샷을 클립보드에 담고 붙여넣기 단축키(Ctrl+Alt+V)를 누르면
docs/public/images/<문서이름>/에 저장되고 링크까지 삽입된다. (Paste Image 확장)
직접 넣을 때도 docs/public/ 아래에 두고 /images/foo.png처럼 public을 뺀 절대경로로 참조한다.
코드블록 언어를 mermaid로 쓰면 그대로 그려진다.
```mermaid
flowchart LR
A[초안] --> B[정리] --> C[공개]
```
VitePress 기본 로컬 검색은 공백·구두점으로만 잘라서, 한국어는 조사가 붙은 어절이 통째로 색인된다.
이 위키는 한글 구간을 원본 + bigram으로 색인해 어절 중간 단어로도 찾을 수 있게 해 두었다.
docs/.vitepress/config.mts 의 tokenize 가 그 부분이다.
.
├─ .devcontainer/ Node 24 개발 컨테이너
├─ .vscode/ 확장 추천 · 에디터 설정 · 태스크
├─ .github/workflows/ GitHub Pages 자동 배포
├─ docs/
│ ├─ .vitepress/
│ │ ├─ config.mts 사이트 설정 · 검색 토크나이저 · mermaid
│ │ ├─ scan.mts docs 폴더 스캔 (사이드바·데이터 로더 공용)
│ │ ├─ sidebar.mts 사이드바 · 상단 메뉴 자동 생성
│ │ └─ theme/
│ │ ├─ index.ts components/*.vue 전역 자동 등록
│ │ ├─ style.css 한글 가독성 · 브랜드 색
│ │ ├─ components/ CategoryGrid · TagIndex · RecentUpdates
│ │ └─ data/ 빌드 타임 데이터 로더
│ ├─ index.md 홈
│ ├─ tags.md 태그 인덱스
│ ├─ public/ 이미지 · 첨부파일
│ └─ <카테고리>/ npm run new 로 생성
├─ templates/ 문서 템플릿 (docs 밖이라 검색·사이드바에 안 잡힌다)
└─ scripts/new-doc.mjs npm run new
main에 push하면 GitHub Actions가 빌드해서 GitHub Pages에 올린다.
git add . && git commit -m "문서 추가" && git push최초 1회만 저장소 설정이 필요하다.
- GitHub 저장소 → Settings → Pages
- Source 를 GitHub Actions 로 변경
워크플로는
fetch-depth: 0으로 전체 히스토리를 받아 온다. "최근 업데이트" 목록이 git 커밋 시각을 쓰기 때문에, 얕은 클론이면 모든 문서의 날짜가 같아진다.
| 바꾸고 싶은 것 | 어디를 고치나 |
|---|---|
| 사이트 제목·설명 | docs/.vitepress/config.mts 의 title / description |
| 배포 주소가 바뀜 | 같은 파일의 base (사용자 페이지면 '/') |
| 색상·폰트 | docs/.vitepress/theme/style.css |
| 최근 목록 개수 | docs/.vitepress/theme/data/recent.data.mts 의 LIMIT |
| 문서 템플릿 | templates/*.md |
| 새 컴포넌트 | docs/.vitepress/theme/components/ 에 .vue 추가 → 바로 사용 가능 |
⚠️ config.mts안에서 함수를 쓸 때(예: 검색tokenize)는 바깥 변수를 참조하면 안 된다. VitePress가 함수를toString()으로 직렬화해 브라우저에서 되살리기 때문에, 클로저가 사라져 런타임 에러가 나고 검색 결과가 통째로 비어 버린다.
- 첫 실행이 느린 건 정상이다. Vite가 mermaid 같은 무거운 의존성을 처음 한 번 미리 번들한다(
docs/.vitepress/cache/). 이후로는 캐시를 재사용해 빠르다. mermaid는config.mts의optimizeDeps.include에 넣어 두어, 다이어그램 있는 페이지가 수백 개의 개별 모듈로 쪼개지지 않게 했다. - 새 문서·카테고리가 사이드바에 안 보이면 dev 서버를 다시 시작한다. 사이드바는 설정을 읽을 때 한 번 계산된다(문서 페이지 자체는 URL로 바로 열린다). 문서 내용 편집은 저장 즉시 반영된다.
- 저장이 갈수록 느려지지 않는다. "최근 업데이트"는 문서마다 git을 부르지 않고 히스토리를 한 번에 읽으므로(
recent.data.mts), 문서가 많아져도 저장 속도가 유지된다. - 그래도 이상하면 캐시를 지우고 다시 띄운다:
docs/.vitepress/cache폴더 삭제 후npm run docs:dev.