🚀 VS Code + MkDocs + GitHub Pages 생성

1. 준비

필수 설치:

- Python (3.8 이상)
- Git
- VS Code

2. 로컬 MkDocs 프로젝트 생성

터미널(VS Code 내 터미널)에서:

# MkDocs 설치 (Material 테마 포함)
pip install mkdocs-material

# 프로젝트 생성
mkdocs new my-tips

cd my-tips

생성된 구조:

my-tips/
  ├─ docs/
  │    └─ index.md     ← 홈페이지
  └─ mkdocs.yml        ← 설정 파일

3. VS Code에서 작성

docs/ 폴더 안에 원하는 만큼 .md 파일 생성

예:

docs/
  index.md
  linux.md
  networking.md
  windows.md

mkdocs.yml 안에 네비게이션 구성 (사이드바 역할):

site_name: My Tips
site_url: https://appi77.github.io/my-tips/
theme:
  name: material
#nav:
#  - 홈: index.md
#  - 리눅스: linux.md
#  - 네트워크: networking.md
#  - 윈도우: windows.md
#  - 사이트 관리: site_management.md
#  - MkDocs 매뉴얼: mkdocs_manual.md
plugins:
  - awesome-pages

.gitignore 안에 site/ 폴더 제외 추가

4. 로컬 미리보기

mkdocs serve

→ 브라우저에서 http://127.0.0.1:8000 접속
👉 UI 확인 가능

5. GitHub에 올리기

TERMINAL 에사:

git init
git add .
git commit -m "첫 MkDocs 사이트"
git branch -M main
git remote add origin https://github.com/appi77/my-tips.git
git push -u origin main

또는 GUI에서:

Source Control(Ctrl+Shift+G)에서
Initialize Repository 클릭
커밋 메시지 입력 후 'Commit' 클릭
'Sync Changes' 클릭 후 원격 저장소(/appi77/my-tips.git) 선택 또는 지정

6. GitHub Pages 배포

TERMINAL에서 배포 명령 실행

mkdocs gh-deploy

명령 실행 시 사이트 파일 자동으로 gh-pages 브랜치 업로드

업로드 후 GitHub 저장소에서 다음 항목 확인 - Settings → Pages → Source - Deploy from a branch 선택 - Branch gh-pages 설정

사이트 확인 - https://username.github.io/it-tips

7. GitHub Actions를 통한 자동 배포

GitHub에 push 시 MkDocs 사이트 자동 배포를 위한 워크플로우 파일 설정

워크플로우 파일 경로

.github/workflows/deploy-mkdocs.yml

워크플로우 파일 예시

name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install mkdocs-material mkdocs-awesome-pages-plugin

      - name: Build and deploy
        run: |
          mkdocs gh-deploy --force

main 브랜치에 파일 추가 또는 수정 후 push로 사이트 자동 배포

GitHub Actions 권한 설정

저장소의 Settings → Actions → General에서
Workflow permissions를 "Read and write permissions"로 설정
Allow GitHub Actions to create and approve pull requests도 체크
위 설정을 해야 gh-pages 브랜치에 정상적으로 배포됨

8. 다른 저장소를 사용하여 배포하는 방법

1. Personal Access Token(PAT) 생성 및 등록

GitHub에서 Fine-grained token 생성
권한: appi77.github.io 저장소에 "Contents: Read and write" 부여
토큰 이름: MY_TOKEN_FOR_WEB_DEPLOY
등록: my-tips 저장소 → Settings → Secrets and variables → Actions → New repository secret
Name: MY_TOKEN_FOR_WEB_DEPLOY
Value: 생성된 토큰 값

2. MkDocs 사이트를 다른 저장소(appi77.github.io)에 배포하는 명령어

mkdocs gh-deploy --remote-name userpage --remote-branch main

3. 자동 배포 워크플로(yml) 예시

.github/workflows/deploy-to-userpage.yml:

name: Deploy to appi77.github.io

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: pip install mkdocs-material mkdocs-awesome-pages-plugin

      - name: Build site
        run: mkdocs build

      - name: Deploy to appi77.github.io
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          cd site
          git init
          git remote add origin https://x-access-token:${{ secrets.MY_TOKEN_FOR_WEB_DEPLOY }}@github.com/appi77/appi77.github.io.git
          git checkout -b main
          git add .
          git commit -m "Deploy from my-tips"
          git push --force origin main

4. 참고

위 방법으로 my-tips 저장소에 커밋할 때마다 appi77.github.io(public)에 자동으로 배포됨
토큰은 반드시 "Contents: Read and write" 권한이 있어야 함
기존 커밋 이력에 민감정보가 있으면 push가 거부될 수 있으니 주의

🎯 정리

VS Code에서 Markdown 작성
mkdocs serve로 로컬 미리보기
git push + mkdocs gh-deploy → GitHub Pages 자동 배포