100일 챌린지 Day 77 - Git 저장소로서의 Wiki 활용, 로컬 편집, 그리고 고급 마크다운 기능을 마스터합니다.
⏱️ 예상 학습 시간: 45-50분 📚 난이도: ⭐⭐⭐ (중급)
배울 내용
- Wiki를 Git 저장소로 관리하기
- 로컬에서 Wiki 편집하기
- 이미지와 첨부 파일 관리
- 고급 마크다운 활용
- 버전 관리와 이력 추적
- Wiki 백업과 마이그레이션
시작하기 전에
이 내용은 다음 개념을 알고 있다면 더 쉽게 이해할 수 있습니다:
- ✅ [Day 76 - GitHub Wiki 기본]
- ✅ Git 기본 명령어 (clone, commit, push)
- ✅ 터미널/커맨드라인 사용 경험
- ✅ 마크다운 문법 기본
Day 76에서 Wiki를 웹에서 만들어봤다면, 이번엔 더 파워풀한 로컬 편집 방법을 배웁니다!
1. Wiki는 Git 저장소다
Wiki의 실체
중요: GitHub Wiki는 별도의 Git 저장소입니다!
1
2
3
4
5
6
7
8
| 메인 저장소:
https://github.com/user/repo.git
Wiki 저장소:
https://github.com/user/repo.wiki.git
^^^^^ .wiki 추가
→ 두 개의 독립적인 Git 저장소
|
Wiki 저장소 구조
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| repo.wiki/
├── Home.md (Home 페이지)
├── Installation.md (설치 가이드)
├── Quick-Start.md (빠른 시작)
├── Configuration.md (설정)
├── API-Reference.md (API 문서)
├── _Sidebar.md (사이드바)
├── _Footer.md (푸터)
└── images/ (이미지 폴더, 직접 생성)
├── logo.png
├── screenshot1.png
└── diagram.svg
특징:
- 각 페이지는 .md 파일
- 페이지 이름 = 파일 이름
- 공백은 하이픈(-)으로
|
Wiki Clone하기
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # Wiki 저장소 클론
git clone https://github.com/user/repo.wiki.git
# 또는 SSH
git clone git@github.com:user/repo.wiki.git
# 디렉토리로 이동
cd repo.wiki
# 파일 확인
ls -la
# Home.md
# Installation.md
# _Sidebar.md
# _Footer.md
|
주의사항:
1
2
3
4
5
6
7
| ❌ 메인 저장소와 Wiki는 별개
git clone https://github.com/user/repo.git ← 메인
git clone https://github.com/user/repo.wiki.git ← Wiki
✅ 별도 디렉토리에 클론
~/projects/repo/ ← 메인 저장소
~/projects/repo-wiki/ ← Wiki 저장소
|
2. 로컬에서 Wiki 편집하기
로컬 편집 워크플로우
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| # 1. Wiki 저장소 클론 (최초 1회)
git clone https://github.com/user/repo.wiki.git
cd repo.wiki
# 2. 최신 변경사항 가져오기
git pull origin master
# 3. 페이지 편집 (좋아하는 에디터 사용)
vim API-Reference.md
# 또는
code API-Reference.md # VS Code
nano API-Reference.md # Nano
# 4. 변경사항 확인
git status
git diff
# 5. 커밋
git add API-Reference.md
git commit -m "docs: Update API endpoints section"
# 6. 푸시
git push origin master
# → GitHub Wiki 페이지에 즉시 반영!
|
새 페이지 생성
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| # 새 페이지 파일 생성
cat > Troubleshooting.md << 'EOF'
# 트러블슈팅
자주 발생하는 문제와 해결 방법입니다.
## 설치 오류
### npm install 실패
```bash
# 캐시 정리
npm cache clean --force
# 재설치
rm -rf node_modules
npm install
|
EOF
Git에 추가
git add Troubleshooting.md git commit -m “docs: Add troubleshooting guide” git push origin master
→ Wiki에 “Troubleshooting” 페이지 생성됨
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
### 페이지 삭제
```bash
# 페이지 파일 삭제
git rm Old-Page.md
# 커밋
git commit -m "docs: Remove outdated page"
# 푸시
git push origin master
# → Wiki에서 "Old-Page" 삭제됨
|
페이지 이름 변경
1
2
3
4
5
6
7
8
9
10
| # 파일명 변경
git mv Old-Name.md New-Name.md
# 커밋
git commit -m "docs: Rename page for clarity"
# 푸시
git push origin master
# → Wiki 페이지 이름이 변경됨
|
3. 이미지와 첨부 파일 관리
이미지 업로드 방법
방법 1: 웹 인터페이스에서 드래그 앤 드롭
1
2
3
4
5
| 1. Wiki 페이지 편집 모드
2. 이미지 파일을 에디터로 드래그
3. 자동으로 업로드되고 마크다운 생성됨:
|
방법 2: 로컬에서 관리
1
2
3
4
5
6
7
8
9
10
| # images 폴더 생성
mkdir -p images
# 이미지 복사
cp ~/Downloads/architecture.png images/
# Git에 추가
git add images/architecture.png
git commit -m "docs: Add architecture diagram"
git push origin master
|
마크다운에서 참조:
1
2
3
4
5
6
7
8
9
| # 아키텍처
# 또는 상대 경로
# 크기 조절 (HTML 사용)
<img src="images/screenshot.png" width="600" alt="Screenshot">
|
이미지 관리 베스트 프랙티스
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| # 구조화된 이미지 폴더
images/
├── diagrams/
│ ├── architecture.svg
│ ├── workflow.svg
│ └── database-schema.png
├── screenshots/
│ ├── installation-step1.png
│ ├── installation-step2.png
│ └── dashboard.png
├── logos/
│ ├── logo.png
│ ├── logo-small.png
│ └── favicon.ico
└── icons/
├── warning.svg
└── info.svg
명명 규칙:
✅ descriptive-name.png (설명적)
✅ feature-screenshot-01.png (순서)
❌ img1.png (의미 없음)
❌ Screen Shot 2024-01-01.png (공백)
|
외부 이미지 링크
1
2
3
4
5
6
7
8
9
10
11
| # GitHub 저장소의 이미지
# 외부 URL
# Issues/PR의 이미지 재활용
장점: Wiki 저장소 크기 절약
단점: 외부 링크 깨질 수 있음
|
4. 고급 마크다운 활용
코드 블록과 신택스 하이라이팅
1
2
3
4
5
| # JavaScript
```javascript
function hello() {
console.log("Hello Wiki!");
}
|
Python
1
2
| def hello():
print("Hello Wiki!")
|
파일명 포함
const express = require('express');
const app = express();
Diff
1
2
| - const oldValue = 10;
+ const newValue = 20;
|
출력 예시
1
2
| $ npm start
Server running on port 3000
|
1
2
3
4
5
6
7
8
9
10
|
### 테이블
**기본 테이블**:
```markdown
| 명령어 | 설명 | 예시 |
|--------|------|------|
| `start` | 서버 시작 | `npm start` |
| `build` | 빌드 | `npm run build` |
| `test` | 테스트 실행 | `npm test` |
|
정렬:
1
2
3
4
| | 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:---------|:-----------:|----------:|
| Left | Center | Right |
| Text | Text | Text |
|
복잡한 테이블:
1
2
3
4
5
6
| | API | Method | Endpoint | 인증 | 설명 |
|-----|--------|----------|------|------|
| User | GET | `/api/users` | ✅ | 사용자 목록 |
| User | POST | `/api/users` | ✅ | 사용자 생성 |
| User | GET | `/api/users/:id` | ✅ | 사용자 조회 |
| Auth | POST | `/api/auth/login` | ❌ | 로그인 |
|
태스크 리스트
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| ## 설치 체크리스트
- [x] Node.js 설치 확인
- [x] npm 버전 확인
- [ ] 프로젝트 클론
- [ ] 의존성 설치
- [ ] 환경 변수 설정
- [ ] 개발 서버 실행
## 릴리스 준비
- [x] 코드 리뷰 완료
- [x] 테스트 통과
- [x] 문서 업데이트
- [ ] 릴리스 노트 작성
- [ ] 버전 태그 생성
|
인용구와 알림
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| # 기본 인용구
> 이것은 인용구입니다.
# 중첩 인용구
> 첫 번째 레벨
>> 두 번째 레벨
>>> 세 번째 레벨
# GitHub 스타일 알림
> **Note**
> 유용한 정보를 제공합니다.
> **Warning**
> 주의가 필요한 내용입니다.
> **Important**
> 중요한 내용입니다.
|
세부 정보 (Details/Summary)
1
2
3
4
5
6
7
| <details>
<summary>클릭하여 더 보기</summary>
여기에 숨겨진 내용을 작성합니다.
```bash
npm install express
|
</details>
고급 설정
### 환경 변수 | 변수 | 설명 | 기본값 | |------|------|--------| | PORT | 서버 포트 | 3000 | | NODE_ENV | 환경 | development | 1
2
3
4
5
6
7
8
9
10
11
12
|
### 다이어그램 (Mermaid)
**플로우차트**:
```markdown
```mermaid
graph TD
A[Start] --> B{Check}
B -->|Yes| C[Process]
B -->|No| D[Skip]
C --> E[End]
D --> E
|
1
2
3
4
5
6
7
8
9
|
**시퀀스 다이어그램**:
```markdown
```mermaid
sequenceDiagram
Client->>Server: Request
Server->>Database: Query
Database-->>Server: Result
Server-->>Client: Response
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
**간트 차트**:
```markdown
```mermaid
gantt
title 프로젝트 일정
dateFormat YYYY-MM-DD
section Phase 1
설계 :a1, 2024-01-01, 30d
개발 :a2, after a1, 45d
section Phase 2
테스트 :a3, after a2, 15d
배포 :a4, after a3, 7d
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
### 수식 (Math)
```markdown
# 인라인 수식
질량-에너지 등가 원리: $E = mc^2$
# 블록 수식
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
# 복잡한 수식
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
|
💡 초보자 팁 Git으로 Wiki를 관리하는 게 복잡하게 느껴진다면, 웹 인터페이스만 사용해도 됩니다! 로컬 편집은 큰 문서를 다루거나, VS Code 같은 에디터를 선호할 때 유용합니다. Mermaid 다이어그램이 어렵다면 처음엔 간단한 flowchart만 사용해보세요. 복잡한 것은 나중에!
5. 버전 관리와 이력 추적
변경 이력 확인
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| # 커밋 로그 확인
git log
# 간단한 로그
git log --oneline
# 특정 파일의 이력
git log -- API-Reference.md
# 그래프로 보기
git log --graph --oneline
# 누가 언제 수정했는지
git blame API-Reference.md
|
특정 시점으로 복원
1
2
3
4
5
6
7
8
9
10
11
12
13
| # 커밋 해시 확인
git log --oneline
# abc1234 docs: Update API docs
# def5678 docs: Add examples
# ghi9012 docs: Initial API docs
# 특정 커밋으로 이동
git checkout def5678 API-Reference.md
# 확인 후 복원하기
git add API-Reference.md
git commit -m "docs: Revert API docs to previous version"
git push origin master
|
변경 내용 비교
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| # 현재 변경사항 확인
git diff
# 특정 파일만
git diff API-Reference.md
# 스테이징된 변경사항
git diff --staged
# 두 커밋 간 차이
git diff abc1234 def5678
# 특정 커밋과 현재의 차이
git diff abc1234 API-Reference.md
|
브랜치 사용하기
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| # 새 브랜치 생성 (큰 변경 작업 시)
git checkout -b major-docs-update
# 여러 파일 수정
vim Home.md
vim Installation.md
vim API-Reference.md
# 커밋
git add .
git commit -m "docs: Major documentation overhaul"
# master에 병합
git checkout master
git merge major-docs-update
# 푸시
git push origin master
# 브랜치 삭제
git branch -d major-docs-update
|
6. Wiki 백업과 마이그레이션
전체 Wiki 백업
1
2
3
4
5
6
7
8
9
| # Wiki 전체 백업
git clone https://github.com/user/repo.wiki.git backup-wiki
cd backup-wiki
# 압축
tar -czf wiki-backup-$(date +%Y%m%d).tar.gz .
# 외부 저장소에 백업
cp wiki-backup-*.tar.gz /backup/location/
|
자동 백업 스크립트
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| #!/bin/bash
# wiki-backup.sh
WIKI_URL="https://github.com/user/repo.wiki.git"
BACKUP_DIR="$HOME/wiki-backups"
DATE=$(date +%Y%m%d-%H%M%S)
BACKUP_PATH="$BACKUP_DIR/wiki-$DATE"
# 백업 디렉토리 생성
mkdir -p "$BACKUP_DIR"
# Wiki 클론
git clone "$WIKI_URL" "$BACKUP_PATH"
# 압축
cd "$BACKUP_DIR"
tar -czf "wiki-$DATE.tar.gz" "wiki-$DATE"
rm -rf "wiki-$DATE"
# 오래된 백업 삭제 (30일 이상)
find "$BACKUP_DIR" -name "wiki-*.tar.gz" -mtime +30 -delete
echo "Backup completed: wiki-$DATE.tar.gz"
|
Cron으로 자동화:
1
2
3
| # crontab -e
# 매일 새벽 2시에 백업
0 2 * * * /path/to/wiki-backup.sh
|
다른 저장소로 마이그레이션
1
2
3
4
5
6
7
8
9
10
11
12
13
| # 기존 Wiki 클론
git clone https://github.com/old-user/old-repo.wiki.git
cd old-repo.wiki
# 새 저장소를 remote로 추가
git remote add new https://github.com/new-user/new-repo.wiki.git
# 푸시
git push new master
# 확인
# https://github.com/new-user/new-repo/wiki
|
Wiki를 일반 저장소로 변환
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| # Wiki 클론
git clone https://github.com/user/repo.wiki.git
# docs 디렉토리로 이동
cd repo.wiki
mkdir -p ../repo/docs
cp *.md ../repo/docs/
# 이미지 복사
cp -r images ../repo/docs/
# 메인 저장소에 커밋
cd ../repo
git add docs/
git commit -m "docs: Import wiki to docs/"
git push origin main
|
7. 실전 팁과 워크플로우
팀 협업 워크플로우
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| # 팀원 A
git clone https://github.com/team/project.wiki.git
cd project.wiki
# 브랜치 생성
git checkout -b feature/api-docs
# 작업
vim API-Reference.md
git add API-Reference.md
git commit -m "docs: Add authentication section"
# 푸시
git push origin feature/api-docs
# → GitHub에서 병합 (또는 직접 master에 merge)
# 팀원 B
git pull origin master # 최신 변경사항 받기
|
대용량 파일 처리
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # Git LFS 사용 (큰 이미지/동영상)
git lfs install
# LFS 추적 설정
git lfs track "*.mp4"
git lfs track "*.pdf"
git lfs track "images/*.psd"
# .gitattributes에 자동 추가됨
git add .gitattributes
# 일반적으로 사용
git add large-video.mp4
git commit -m "docs: Add tutorial video"
git push origin master
|
템플릿 활용
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
| # 페이지 템플릿 생성
cat > .templates/page-template.md << 'EOF'
# Page Title
Brief description of the page.
## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
---
## Section 1
Content here.
## Section 2
Content here.
---
## Related Pages
- [[Home]]
- [[Other Page]]
EOF
# 새 페이지 생성 시 복사
cp .templates/page-template.md New-Feature.md
vim New-Feature.md
|
직접 해보기 (30-35분)
실습을 통해 배운 내용을 체화해봅시다!
📝 실습 1: Wiki 로컬로 클론하기 (5분)
1
2
3
4
5
| - [ ] 1. Day 76에서 만든 Wiki 저장소 확인
- [ ] 2. 터미널에서 git clone [repo].wiki.git 실행
- [ ] 3. 클론된 폴더 확인 (ls 또는 파일 탐색기)
- [ ] 4. .md 파일들 확인
- [ ] 5. VS Code로 폴더 열기
|
📝 실습 2: 로컬에서 페이지 수정하기 (10분)
1
2
3
4
5
6
| - [ ] 1. 기존 페이지 하나 선택하여 편집
- [ ] 2. VS Code 마크다운 미리보기 켜기
- [ ] 3. 내용 수정하고 저장
- [ ] 4. git status로 변경사항 확인
- [ ] 5. git add, commit, push 실행
- [ ] 6. GitHub에서 변경사항 확인
|
📝 실습 3: 이미지 추가하기 (10분)
1
2
3
4
5
6
| - [ ] 1. images 폴더 생성
- [ ] 2. 이미지 파일 복사
- [ ] 3. 페이지에 이미지 마크다운 추가
- [ ] 4. git add로 이미지와 페이지 모두 추가
- [ ] 5. commit & push
- [ ] 6. GitHub에서 이미지 표시 확인
|
📝 실습 4: 고급 마크다운 활용하기 (10분)
1
2
3
4
5
| - [ ] 1. 테이블 만들기 (최소 3x3)
- [ ] 2. 코드 블록 추가 (신택스 하이라이팅)
- [ ] 3. Task List 추가
- [ ] 4. Mermaid 플로우차트 추가 (간단한 것)
- [ ] 5. 모두 commit & push
|
실습 완료 후: 이제 로컬 에디터로 Wiki를 프로처럼 관리할 수 있습니다!
😰 어려우시다면
이 내용이 어렵게 느껴진다면:
- Git 명령어가 낯선 경우
- 웹 인터페이스로만 사용해도 괜찮습니다
- 나중에 Git을 더 배우고 나서 시도하세요
- 기본 명령어만 익히면 됩니다 (clone, add, commit, push)
- 로컬 편집이 복잡한 경우
- VS Code 설치하면 훨씬 쉽습니다
- 마크다운 미리보기로 결과를 바로 확인
- 처음엔 간단한 수정부터 시작하세요
- Mermaid 문법이 어려운 경우
- 간단한 flowchart만 사용하세요
- 온라인 Mermaid 에디터 사용 (mermaid.live)
- 예제를 복사해서 수정하는 것으로 시작
- 이미지 경로가 헷갈리는 경우
- images/파일명.png 형식만 기억하세요
- 상대 경로만 사용 (./images/ 또는 images/)
- 웹 인터페이스에서 드래그 앤 드롭이 더 쉬울 수 있습니다
- 백업이 중요한지 모르겠는 경우
- Wiki도 Git 저장소라 GitHub에 자동 백업됩니다
- 추가 로컬 백업은 보험입니다
- 중요한 프로젝트만 자동 백업 설정하세요
- 복습이 필요하다면
- Day 76: Wiki 기본 복습
- Git 기본 명령어 복습
- 마크다운 치트시트 참고
꼭 기억하세요: 로컬 편집은 선택사항입니다. 웹 인터페이스만으로도 충분히 훌륭한 Wiki를 만들 수 있습니다. 로컬 편집은 더 편하고 빠르게 작업하고 싶을 때 사용하세요!
정리
완료 체크:
- Wiki를 Git 저장소로 클론할 수 있다
- 로컬에서 Wiki를 편집하고 푸시할 수 있다
- 이미지를 효과적으로 관리할 수 있다
- 고급 마크다운 기능(코드, 테이블, 다이어그램)을 활용할 수 있다
- 버전 관리와 이력 추적을 할 수 있다
- Wiki를 백업하고 마이그레이션할 수 있다
- 직접 실습을 완료했다
핵심 요약:
- Git 저장소: Wiki는
.wiki.git으로 끝나는 별도 저장소 - 로컬 편집: Clone → Edit → Commit → Push
- 이미지 관리:
images/ 폴더에 구조화하여 저장 - 고급 마크다운: 코드 블록, 테이블, Mermaid 다이어그램, 수식
- 버전 관리: Git의 모든 기능 활용 (log, diff, blame, branch)
- 백업: 정기적으로 전체 Wiki 클론 및 압축
실전 팁:
- ✅ VS Code로 Wiki 편집하면 마크다운 미리보기 가능
- ✅ 큰 변경 작업은 브랜치에서 진행
- ✅ 커밋 메시지에
docs: 접두사 사용 - ✅ 이미지는
images/ 폴더에 주제별 정리 - ✅ 대용량 파일은 Git LFS 활용
- ✅ 매일 또는 매주 자동 백업 설정
- ✅ Mermaid로 다이어그램을 코드로 관리
- ✅
git blame으로 문서 담당자 파악 - ✅ 템플릿으로 일관된 페이지 구조 유지
다음: Day 78 - Discussions →
