MkDocs로 GitHub Pages에 위키 사이트 쉽게 만들기
이번 포스팅에서는 MkDocs를 이용하여 간단하게 위키 형태의 사이트를 GitHub Pages로 만드는 방법을 알아보겠습니다.
📌 준비물
- Python
- Git
- GitHub 계정
✅ MkDocs 설치 및 설정하기
프로젝트 환경을 설정하는 최적의 방법은 아래와 같습니다.
mkdir my-wiki
cd my-wiki
# 원하는 Python 버전 설정 (예시)
pyenv local 3.12.2
# 가상환경 설정
python -m venv .venv
source .venv/bin/activate
# MkDocs 설치
pip install mkdocs mkdocs-material
# MkDocs 프로젝트 생성
mkdocs new .
✅ GitHub 저장소 연결
GitHub에 저장소를 만든 후 연결합니다.
1. GitHub 저장소 만들기
https://github.com/new 에서 저장소(repository)를 생성합니다.
2. 현재 디렉터리를 새로운 Git 저장소로 초기화합니다.
.git 폴더가 생성되어, 이 폴더 아래에서 모든 버전 관리가 시작됩니다.
git init
3. git 저장소에 저장할 필요가 없는 파일들을 제외하도록 .gitignore 파일을 만듭니다.
# .gitignore 생성
cat << EOF > .gitignore
.venv/
venv/
__pycache__/
site/
*.pyc
.DS_Store
EOF
4. 최초 커밋
# 초기 commit
git add .
git commit -m "Initial MkDocs commit"
5. GitHub 원격 저장소 연결
# GitHub 저장소 연결
git remote add origin https://github.com/<username>/<repo-name>.git
# e.g. ssh 방식 GitHub 저장소 연결
# git remote add origin git@github.com:<username>/<repo-name>.git # ssh 방식
# e.g. junho85 계정의 my-wiki 저장소 연결
# git remote add origin git@github.com:junho85/my-wiki.git
6. 브랜치 이름(main) 세팅
# 기본 브랜치명을 main으로 변경
git branch -M main
7. 원격 저장소에 코드 업로드(푸시)
# 원격 저장소로 푸시
git push -u origin main
✅ 사이트 배포하기
mkdocs gh-deploy
GitHub 저장소의 Pages 탭에서 생성된 사이트 URL을 확인할 수 있습니다.
https://<username>.github.io/<repo-name>/
된 사이트 URL을 확인할 수 있습니다.
username이 junho85이고 repo-name이 my-wiki 라면 주소는 다음과 같습니다.
https://junho85.github.io/my-wiki/
접속해 보면 다음과 같은 화면이 나타납니다. index.md 파일을 일부 수정하고, 문서를 좀 더 추가한 모습입니다.
GitHub > Settings > Pages 에서 배포된 주소를 확인할 수 있고, 설정들을 확인하거나 수정할 수 있습니다.
https://github.com/junho85/my-wiki/settings/pages
✅ 위키 문서 추가하기
추가하고 싶은 문서를 docs/ 폴더에 Markdown 파일로 작성한 뒤, mkdocs.yml에서 메뉴를 구성합니다.
예시:
- docs/my-new-page.md 생성
- mkdocs.yml 수정
nav:
- Home: index.md
- My New Page: my-new-page.md
로컬 미리보기 후 배포
mkdocs serve # 로컬 확인
mkdocs gh-deploy # 배포
🎉 이제 쉽고 빠르게 나만의 위키 사이트를 GitHub Pages로 운영할 수 있습니다!