콘텐츠로 이동

MkDocs Material 블로그를 Firebase Hosting에 배포하기: 이 사이트가 올라가는 방법

지금 보고 계신 이 블로그는 MkDocs Material로 빌드해서 Firebase Hosting에 올린 정적 사이트입니다. 글은 마크다운 파일 한 장이고, 배포는 명령어 두 줄이면 끝나죠. 이 글에서는 빈 저장소에서 실제 공개 URL이 뜨기까지의 셋팅 과정을 그대로 정리합니다. 따라 하면 여러분의 글도 https://<프로젝트>.web.app 주소로 바로 올라갑니다.

1. 준비물 — 두 개의 런타임

MkDocs는 파이썬, 배포 도구(Firebase CLI)는 Node 기반입니다. 그래서 환경이 두 갈래로 나뉩니다.

# (1) MkDocs — 파이썬 가상환경
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt          # mkdocs-material 등

# (2) Firebase CLI — Node
npm install -g firebase-tools             # 이미 있다면 생략
firebase login                            # 브라우저로 구글 로그인 (최초 1회)

가상환경(.venv)을 쓰는 이유는 간단합니다. mkdocs 버전이 시스템 파이썬과 섞이면 "내 컴퓨터에선 됐는데" 문제가 생기거든요. 프로젝트 폴더 안에 환경을 가두면 재현이 쉽습니다.

2. Firebase 프로젝트 연결

Firebase 콘솔에서 프로젝트를 하나 만들어 둡니다(여기선 trendcompass-mkdocs). 그다음 로컬 저장소를 그 프로젝트에 연결합니다.

firebase use --add        # 목록에서 프로젝트 선택 → .firebaserc 생성

이 명령은 .firebaserc라는 작은 파일을 만들어 "이 폴더는 이 Firebase 프로젝트에 배포한다"를 기록합니다. 직접 적어도 됩니다.

.firebaserc
{
  "projects": {
    "default": "trendcompass-mkdocs"
  }
}

3. 핵심 — firebase.json 한 장

Firebase에게 "빌드된 폴더를 그대로 호스팅하라"고 알려주는 설정입니다. MkDocs는 mkdocs build를 돌리면 결과물을 site/ 폴더에 쏟아내므로, 그 폴더를 public으로 지정합니다.

firebase.json
{
  "hosting": {
    "public": "site",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "cleanUrls": true,
    "trailingSlash": false
  }
}
  • public: "site" — MkDocs 빌드 산출물 폴더. 이게 핵심입니다.
  • cleanUrls: true — /about.html 대신 /about으로 접근. 깔끔한 URL.
  • ignore — 호스팅에 올릴 필요 없는 파일 제외.

4. site_url 채우기 (잊기 쉬운 한 줄)

배포 도메인이 정해졌으면 mkdocs.yml의 site_url을 꼭 채웁니다. 이게 비어 있으면 검색엔진용 sitemap.xml과 canonical 링크가 제대로 생성되지 않아 SEO에서 손해를 봅니다.

mkdocs.yml
site_url: https://trendcompass-mkdocs.web.app

Firebase Hosting은 프로젝트를 만들면 https://<프로젝트ID>.web.app 도메인을 기본으로 줍니다. 커스텀 도메인은 나중에 콘솔에서 연결해도 됩니다.

5. 빌드하고 배포하기

이제 두 줄이면 끝입니다.

mkdocs build                      # 마크다운 → site/ 정적 HTML
firebase deploy --only hosting    # site/ → 공개 URL

성공하면 이런 출력이 뜹니다.

✔  Deploy complete!
Hosting URL: https://trendcompass-mkdocs.web.app

배포가 잘 됐는지는 굳이 브라우저를 안 열어도 확인할 수 있습니다.

curl -s -o /dev/null -w "%{http_code}\n" https://trendcompass-mkdocs.web.app
# 200 이면 정상

6. 글을 추가하는 흐름

한 번 셋팅해 두면 이후 운영은 단순합니다.

  1. docs/posts/<slug>/index.md에 글을 쓴다(frontmatter에 date, categories 필수).
  2. mkdocs build && firebase deploy --only hosting.

좌측 메뉴(연도별·주제별)와 홈 피드는 blog 플러그인이 각 글의 frontmatter를 읽어 자동으로 만들어 줍니다. 글이 100개로 늘어도 mkdocs.yml을 손댈 일이 없죠. 운영 비용이 거의 0에 수렴한다는 게 이 조합의 가장 큰 매력입니다.

마치며

요약하면 파이썬으로 빌드, Node로 배포, 그리고 그 사이를 잇는 건 firebase.json의 public: "site" 한 줄입니다. 정적 사이트라 서버 관리도, 보안 패치도 필요 없고, Firebase 무료 한도 안에서 개인 블로그는 사실상 공짜로 운영됩니다. 마크다운만 쓰면 나머지는 자동화되는 이 흐름, 글쓰기에만 집중하고 싶은 분께 추천합니다.