[GitHub 100일 챌린지] Day 76 - GitHub Wiki 만들기

게시 2025/03/16

Day 76 - GitHub Wiki

By YonYonWare

26 분읽는 시간

[GitHub 100일 챌린지] Day 76 - GitHub Wiki 만들기

100일 챌린지 Day 76 - GitHub Wiki로 프로젝트 문서를 체계적으로 관리하고 공유합니다.

⏱️ 예상 학습 시간: 45-50분 📚 난이도: ⭐⭐⭐ (중급)

배울 내용

Wiki의 역할과 README와의 차이점
Wiki 활성화 및 초기 설정
효과적인 페이지 구조 설계
사이드바와 Footer로 네비게이션 만들기
링크와 참조로 페이지 연결하기

시작하기 전에

이 내용은 다음 개념을 알고 있다면 더 쉽게 이해할 수 있습니다:

✅ Markdown 문법 기본
✅ README.md 작성 경험
✅ 프로젝트 문서화의 필요성 이해

Wiki는 README의 확장판이라고 생각하면 쉽습니다. Markdown을 알고 있다면 금방 시작할 수 있어요!

1. GitHub Wiki란?

정의와 목적

GitHub Wiki는 프로젝트의 문서를 협업으로 작성하고 관리하는 도구입니다.

Wiki = 프로젝트 지식 베이스
┌─────────────────────────┐
│ 📖 설치 가이드           │
│ 🔧 설정 방법             │
│ 📚 API 문서              │
│ ❓ FAQ                  │
│ 💡 튜토리얼              │
│ 🏗️ 아키텍처 설명         │
└─────────────────────────┘

목적:
- 사용자 가이드
- 개발자 문서
- 프로젝트 규칙
- 지식 공유

Wiki vs README

구분	README	Wiki
위치	저장소 루트	별도 탭
분량	짧고 간결	상세하고 방대
구조	단일 파일	여러 페이지
용도	프로젝트 소개	상세 문서
검색	파일 내 검색	전체 Wiki 검색
버전 관리	메인 저장소	별도 Git 저장소

활용 예시:

README.md:
- 프로젝트 소개
- 빠른 시작
- 설치 명령어
- 라이선스

Wiki:
- 상세한 설치 가이드 (다양한 OS별)
- API 레퍼런스 (모든 엔드포인트)
- 사용 예제 (다양한 시나리오)
- 아키텍처 설명
- 기여 가이드 상세
- 트러블슈팅
- 버전별 변경사항

Wiki의 장점

✅ 협업: 여러 명이 동시 편집
✅ 구조화: 계층적 페이지 구성
✅ 검색: 전체 문서 빠른 검색
✅ 버전 관리: Git 기반 이력 추적
✅ 접근성: 코드와 분리된 문서
✅ 확장성: 무제한 페이지

2. Wiki 활성화하기

활성화 방법

Repository → Settings → Features

☑ Wikis
  Wikis host documentation for your repository

→ Save

활성화 후:

Repository 탭에 Wiki 추가됨:
Code | Issues | Pull requests | Wiki | ...

처음 접속 시:
┌─────────────────────────────┐
│ Welcome to the wiki!        │
│                             │
│ Create the first page       │
│ [Create the first page]     │
└─────────────────────────────┘

권한 설정

Settings → Wikis

Public Repository:
○ Restrict editing to collaborators only
● Allow everyone to edit (기본)

Private Repository:
● Restrict to collaborators (자동)

권한 레벨:
- Read: Wiki 읽기만
- Write: Wiki 편집 가능
- Admin: Wiki 설정 변경 가능

3. 첫 페이지(Home) 만들기

Home 페이지의 중요성

Home = Wiki의 얼굴

역할:
프로젝트 소개
목차 (전체 구조)
빠른 링크
검색 안내

Home 페이지 예시

기본 구조:

  
# MyProject Wiki

환영합니다! 이 Wiki는 MyProject의 모든 문서를 담고 있습니다.

## 🚀 빠른 시작

처음 시작하시나요? 아래 순서대로 따라해보세요:

1. [[설치 가이드|Installation]] - 프로젝트 설치 방법
2. [[기본 사용법|Quick Start]] - 5분 안에 시작하기
3. [[설정 가이드|Configuration]] - 상세 설정 방법

## 📚 문서 목차

### 사용자 가이드
- [[설치 가이드|Installation]]
  - [[Windows 설치|Installation-Windows]]
  - [[macOS 설치|Installation-macOS]]
  - [[Linux 설치|Installation-Linux]]
- [[기본 사용법|Quick-Start]]
- [[설정 가이드|Configuration]]
- [[CLI 사용법|CLI-Reference]]

### 개발자 가이드
- [[개발 환경 설정|Development-Setup]]
- [[아키텍처 개요|Architecture]]
- [[API 문서|API-Reference]]
- [[기여 가이드|Contributing]]

### 고급 주제
- [[성능 최적화|Performance]]
- [[보안 가이드|Security]]
- [[배포 가이드|Deployment]]
- [[트러블슈팅|Troubleshooting]]

### 기타
- [[FAQ]]
- [[용어집|Glossary]]
- [[릴리스 노트|Release-Notes]]

## 🔍 검색 팁

- 상단 검색창을 이용하세요
- 키워드로 빠르게 찾기
- 사이드바에서 페이지 목록 확인

## 🆘 도움이 필요하신가요?

- 문서에 없는 내용: [Issue 생성](https://github.com/user/repo/issues)
- 문서 개선 제안: Wiki 직접 편집
- 커뮤니티: [Discussions](https://github.com/user/repo/discussions)

## 📝 문서 작성 가이드

Wiki 문서를 작성하고 싶으신가요? [[문서 작성 가이드|Wiki-Guidelines]]를 참고하세요.

실전 팁: 좋은 Home 페이지

포함해야 할 요소:

1. ✅ 환영 메시지
   "MyProject Wiki에 오신 것을 환영합니다!"

2. ✅ 빠른 시작 링크
   신규 사용자가 바로 시작할 수 있는 경로

3. ✅ 체계적인 목차
   모든 페이지를 논리적으로 분류

4. ✅ 검색 안내
   문서 찾는 방법 설명

5. ✅ 도움 받는 방법
   Issue, Discussion 링크

6. ✅ 최종 업데이트 날짜
   문서의 신선도 표시

피해야 할 것:

❌ 너무 긴 내용 (상세 내용은 별도 페이지로)
❌ 목차 없이 링크만 나열
❌ 과도한 스타일링
❌ 업데이트되지 않는 정보

4. 페이지 구조 설계

효과적인 구조

계층적 구조:

Home (루트)
├─ Getting Started (시작하기)
│  ├─ Installation
│  │  ├─ Windows
│  │  ├─ macOS
│  │  └─ Linux
│  ├─ Quick Start
│  └─ Configuration
├─ User Guide (사용자 가이드)
│  ├─ Basic Usage
│  ├─ Advanced Features
│  └─ Best Practices
├─ Developer Guide (개발자 가이드)
│  ├─ Architecture
│  ├─ API Reference
│  ├─ Contributing
│  └─ Testing
├─ Deployment (배포)
│  ├─ Production
│  ├─ Staging
│  └─ Docker
└─ Reference (참고)
   ├─ FAQ
   ├─ Glossary
   └─ Troubleshooting

페이지 명명 규칙

좋은 페이지 이름:

✅ Installation (간결)
✅ Quick-Start (하이픈으로 단어 구분)
✅ API-Reference (명확한 의미)
✅ Configuration-Database (계층 표현)

❌ 설치-방법-상세-가이드-v2 (너무 김)
❌ page1, page2 (의미 없음)
❌ Install (약어 선호 안함)

페이지 생성하기

방법 1: Wiki 페이지에서

Wiki 탭 클릭
"New Page" 버튼
페이지 제목 입력: "Installation"
내용 작성
"Save Page" 클릭

방법 2: 링크를 통해

Home 페이지에서:
[[Installation]]  ← 아직 없는 페이지 링크

→ 링크 클릭 시 자동으로 새 페이지 생성

실전 예시: Installation 페이지

  
# 설치 가이드

MyProject를 설치하는 방법을 설명합니다.

## 목차
- [요구 사항](#요구-사항)
- [패키지 매니저로 설치](#패키지-매니저로-설치)
- [소스에서 빌드](#소스에서-빌드)
- [Docker 설치](#docker-설치)

---

## 요구 사항

MyProject를 실행하려면 다음이 필요합니다:

- **Node.js**: 18.0 이상
- **npm**: 9.0 이상
- **OS**: Windows, macOS, Linux

버전 확인:
```bash
node --version  # v18.0.0 이상
npm --version   # 9.0.0 이상

패키지 매니저로 설치

npm으로 설치

npm install -g myproject

yarn으로 설치

yarn global add myproject

설치 확인

myproject --version

소스에서 빌드

개발 버전을 원하시나요?

  
# 저장소 클론
git clone https://github.com/user/myproject.git
cd myproject

# 의존성 설치
npm install

# 빌드
npm run build

# 실행
npm start

자세한 내용은 [[개발 환경 설정

Development-Setup]]을 참고하세요.

Docker 설치

Docker를 사용한 설치:

docker pull myproject/myproject:latest
docker run -p 3000:3000 myproject/myproject

Docker Compose:

  
version: '3'
services:
  app:
    image: myproject/myproject:latest
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production

자세한 배포 가이드는 [[배포 가이드

Deployment]]를 참고하세요.

문제 해결

설치 중 문제가 발생했나요?

[[트러블슈팅 Troubleshooting]]
[[FAQ]]
Issue 생성

다음 단계

설치가 완료되었다면:

[[기본 사용법 Quick-Start]] - 5분 안에 시작하기
[[설정 가이드|Configuration]] - 프로젝트 설정하기 ```

5. 사이드바 만들기

_Sidebar.md

목적: 모든 페이지에 표시되는 네비게이션

  
# 📖 MyProject Wiki

## 🚀 시작하기
- [[Home]]
- [[설치|Installation]]
- [[빠른 시작|Quick-Start]]

## 📚 사용자 가이드
- [[기본 사용법|Basic-Usage]]
- [[설정|Configuration]]
- [[CLI 참조|CLI-Reference]]

## 🛠️ 개발자 가이드
- [[개발 환경|Development-Setup]]
- [[아키텍처|Architecture]]
- [[API 문서|API-Reference]]
- [[기여하기|Contributing]]

## 🚀 배포
- [[배포 가이드|Deployment]]
- [[Docker|Docker-Setup]]

## 🆘 도움말
- [[FAQ]]
- [[트러블슈팅|Troubleshooting]]
- [[용어집|Glossary]]

---

**버전**: v2.0
**업데이트**: 2024-01-15

생성 방법:

"New Page" 클릭
제목: _Sidebar
내용 작성
Save

→ 모든 페이지 왼쪽에 사이드바 표시

사이드바 팁

효과적인 사이드바:

✅ 중요한 페이지만 (10-15개)
✅ 논리적 그룹화 (이모지로 구분)
✅ 계층 구조 (들여쓰기)
✅ 버전/업데이트 정보

❌ 모든 페이지 나열 (너무 길어짐)
❌ 복잡한 중첩 (3단계 이상)
❌ 과도한 스타일링

_Footer.md

목적: 모든 페이지 하단에 공통 정보

  
---

📝 **문서 개선**: 이 페이지의 [편집 제안하기](https://github.com/user/repo/wiki/_edit)
🐛 **버그 발견**: [Issue 생성](https://github.com/user/repo/issues/new)
💬 **질문하기**: [Discussions](https://github.com/user/repo/discussions)
📧 **이메일**: support@myproject.com

© 2024 MyProject | [라이선스](https://github.com/user/repo/blob/main/LICENSE) | [행동 강령](https://github.com/user/repo/blob/main/CODE_OF_CONDUCT.md)

**마지막 업데이트**: 2024-01-15

7. 링크와 참조

내부 링크

기본 문법:

  
# 같은 단어로 링크
[[Installation]]

# 다른 텍스트로 표시
[[설치 가이드|Installation]]

# 앵커 링크 (페이지 내 섹션)
[[Installation#요구-사항]]

# 다른 페이지의 섹션
[[설치 가이드|Installation#npm으로-설치]]

계층적 페이지:

  
# 상위 페이지
[[Installation]]

# 하위 페이지 (하이픈으로 구분)
[[Installation-Windows]]
[[Installation-macOS]]
[[Installation-Linux]]

# 링크 구조:
Installation
├─ [[Windows|Installation-Windows]]
├─ [[macOS|Installation-macOS]]
└─ [[Linux|Installation-Linux]]

외부 링크

  
# 기본 마크다운 문법
[GitHub](https://github.com)

# 이미지
![Logo](https://example.com/logo.png)

# 저장소 파일 링크
[README](https://github.com/user/repo/blob/main/README.md)

# Issue 참조
#123
user/repo#456

실전 예시: 링크 활용

  
# API 문서

MyProject API의 전체 레퍼런스입니다.

## 개요

API에 대한 기본 개념은 [[아키텍처|Architecture#API-레이어]]를 참고하세요.

## 인증

모든 API 요청은 인증이 필요합니다.
[[인증 가이드|Authentication]]에서 자세한 내용을 확인하세요.

## 엔드포인트

### User API

자세한 내용: [[User API|API-User]]

- `GET /api/users` - [[사용자 목록|API-User#사용자-목록]]
- `POST /api/users` - [[사용자 생성|API-User#사용자-생성]]

### Product API

자세한 내용: [[Product API|API-Product]]

## 에러 처리

API 에러 코드는 [[에러 코드|Error-Codes]]를 참고하세요.

## 예제

실제 사용 예제는 [[예제 모음|Examples]]을 확인하세요.

## 관련 링크

- [API 변경사항](https://github.com/user/repo/blob/main/CHANGELOG.md)
- [Issue 추적](https://github.com/user/repo/issues?q=label:api)
- 질문: [Discussions - API](https://github.com/user/repo/discussions/categories/api)

💡 초보자 팁 Wiki 페이지 구조가 복잡하게 느껴진다면, 처음엔 Home과 2-3개 페이지만 만들어보세요! _Sidebar와 _Footer는 나중에 추가해도 됩니다. 먼저 콘텐츠에 집중하세요. 링크 문법 [[페이지명]]은 페이지가 없어도 작동합니다. 링크를 클릭하면 자동으로 새 페이지가 생성됩니다!

8. 실전 예시: 완전한 Wiki 구조

소규모 프로젝트

Home
├─ Installation
├─ Quick-Start
├─ Configuration
├─ API-Reference
└─ FAQ

_Sidebar.md
_Footer.md

중규모 프로젝트

Home
├─ Getting-Started
│  ├─ Installation
│  │  ├─ Installation-Windows
│  │  ├─ Installation-macOS
│  │  └─ Installation-Linux
│  ├─ Quick-Start
│  └─ Configuration
├─ User-Guide
│  ├─ Basic-Usage
│  ├─ Advanced-Features
│  └─ Best-Practices
├─ API-Reference
│  ├─ Authentication
│  ├─ Endpoints
│  └─ Error-Codes
├─ FAQ
└─ Troubleshooting

_Sidebar.md
_Footer.md

대규모 프로젝트 (기업용)

Home
├─ 1-Getting-Started
│  ├─ 1.1-Installation
│  ├─ 1.2-Quick-Start
│  └─ 1.3-Configuration
├─ 2-User-Guide
│  ├─ 2.1-Basic-Usage
│  ├─ 2.2-Advanced-Features
│  ├─ 2.3-Best-Practices
│  └─ 2.4-Tutorials
├─ 3-Developer-Guide
│  ├─ 3.1-Architecture
│  ├─ 3.2-API-Reference
│  ├─ 3.3-Contributing
│  ├─ 3.4-Testing
│  └─ 3.5-Code-Style
├─ 4-Deployment
│  ├─ 4.1-Production
│  ├─ 4.2-Staging
│  ├─ 4.3-Docker
│  └─ 4.4-Kubernetes
├─ 5-Operations
│  ├─ 5.1-Monitoring
│  ├─ 5.2-Logging
│  ├─ 5.3-Backup
│  └─ 5.4-Security
├─ 6-Reference
│  ├─ 6.1-FAQ
│  ├─ 6.2-Glossary
│  ├─ 6.3-Troubleshooting
│  └─ 6.4-Release-Notes
└─ 7-Community
   ├─ 7.1-Code-of-Conduct
   ├─ 7.2-Support
   └─ 7.3-Roadmap

_Sidebar.md
_Footer.md
Wiki-Guidelines.md (문서 작성 가이드)

직접 해보기 (25-30분)

실습을 통해 배운 내용을 체화해봅시다!

📝 실습 1: Wiki 활성화 및 Home 페이지 만들기 (10분)

- [ ] 1. 연습용 리포지토리에서 Wiki 활성화
- [ ] 2. 첫 페이지(Home) 생성
- [ ] 3. 환영 메시지와 프로젝트 소개 작성
- [ ] 4. "빠른 시작" 섹션 추가
- [ ] 5. 목차 작성 (최소 3개 섹션)

📝 실습 2: 페이지 생성 및 링크 연결 (10분)

- [ ] 1. Installation 페이지 생성
- [ ] 2. Quick-Start 페이지 생성
- [ ] 3. FAQ 페이지 생성
- [ ] 4. Home 페이지에서 각 페이지로 링크 추가
- [ ] 5. 각 페이지에 "다음 단계" 링크 추가

📝 실습 3: _Sidebar와 _Footer 만들기 (5분)

- [ ] 1. _Sidebar 페이지 생성
- [ ] 2. 주요 페이지 링크를 카테고리별로 정리
- [ ] 3. _Footer 페이지 생성
- [ ] 4. Issue, Discussions 링크 추가
- [ ] 5. 다른 페이지 열어서 사이드바/푸터 확인

📝 실습 4: 고급 링크 활용하기 (5분)

- [ ] 1. 앵커 링크 사용해보기 (#섹션명)
- [ ] 2. 다른 페이지 섹션으로 링크하기
- [ ] 3. 외부 링크 추가하기
- [ ] 4. 이미지 추가해보기

실습 완료 후: 이제 프로젝트에 전문적인 문서 시스템을 갖추게 되었습니다!

😰 어려우시다면

이 내용이 어렵게 느껴진다면:

어떤 구조로 만들어야 할지 모르겠는 경우
- 먼저 Home + 2-3개 페이지만 시작하세요
- 유명한 오픈소스 프로젝트의 Wiki 참고
- 필요할 때 페이지를 추가하는 것이 좋습니다
링크 문법이 헷갈리는 경우
- [[페이지명]] - 가장 기본
- [[표시텍스트 페이지명]] - 다르게 표시
- 처음엔 이 두 가지만 사용하세요
페이지 이름을 어떻게 지어야 할지 모르겠는 경우
- 영어로 짓되, 하이픈으로 단어 구분
- Installation, Quick-Start처럼 간결하게
- 한글도 가능하지만 URL이 복잡해집니다
_Sidebar가 너무 길어지는 경우
- 10-15개 항목만 넣으세요
- 모든 페이지를 넣을 필요 없습니다
- 자주 가는 페이지만 선별하세요
README와 Wiki를 어떻게 나눌지 모르겠는 경우
- README: 프로젝트 소개 + 빠른 시작 (1페이지)
- Wiki: 상세 가이드, 튜토리얼, API 문서 (여러 페이지)
복습이 필요하다면
- Markdown 문법 복습
- 다른 오픈소스 프로젝트의 Wiki 둘러보기
- GitHub Wiki 공식 문서 참고

꼭 기억하세요: Wiki는 점진적으로 성장합니다. 처음부터 완벽한 구조를 만들려고 하지 마세요. 필요한 문서를 하나씩 추가하다 보면 자연스럽게 구조가 잡힙니다!

정리

완료 체크:

Wiki의 역할과 README와의 차이를 이해했다
Wiki를 활성화하고 첫 페이지를 만들 수 있다
효과적인 페이지 구조를 설계할 수 있다
Home 페이지에 목차를 작성할 수 있다
_Sidebar로 네비게이션을 만들 수 있다
_Footer로 공통 정보를 추가할 수 있다
내부 링크와 외부 링크를 활용할 수 있다
직접 실습을 완료했다

핵심 요약:

Wiki 목적: 프로젝트의 상세 문서를 체계적으로 관리
Home 페이지: 목차와 빠른 링크로 전체 구조 제공
페이지 구조: 계층적으로 구성하여 논리적 흐름 만들기
_Sidebar: 주요 페이지 네비게이션 제공
_Footer: 공통 정보와 도움말 링크
링크: [[페이지명]] 또는 [[표시텍스트 페이지명]]

실전 팁:

✅ Home 페이지는 Wiki의 얼굴 - 신경 써서 작성
✅ 페이지 이름은 간결하고 의미 있게 (하이픈으로 단어 구분)
✅ 사이드바는 10-15개 주요 페이지만
✅ 3단계 이상 중첩은 피하기
✅ 각 페이지에 “다음 단계” 링크 추가
✅ 목차(ToC)로 긴 페이지 탐색 쉽게
✅ 정기적으로 업데이트 날짜 갱신
✅ 모든 페이지에 “도움말” 섹션 추가

다음: Day 77 - Wiki 고급 →

← Day 75

전체 커리큘럼

Day 77 →

GitHub100일챌린지, Phase08