Copy & Run

MkDocs Material로 팀 문서 사이트 만들기: 빌드, 엄격 모드, 로컬 미리보기

마크다운 파일 몇 개를 MkDocs Material로 정적 사이트로 빌드하고, 깨진 링크를 --strict 옵션으로 잡고, mkdocs serve로 미리 봅니다. 문서를 코드처럼 저장소에서 관리하는 방식의 최소 구성을 실행 결과로 확인합니다.

실습 노트 · 2026-10-28 발행 · 8분 · 2026-10 확인

팀 문서가 메신저와 개인 폴더에 흩어져 있으면 최신 판을 찾기 어렵습니다. 마크다운 파일을 저장소에 두고 MkDocs로 사이트를 만들면 문서도 코드처럼 검토하고 이력을 관리할 수 있습니다. 이 글에서는 가장 작은 구성으로 빌드와 미리보기까지 해 봅니다.

준비물

항목 확인한 값
Python 3.12.10
MkDocs 1.6.1
테마 mkdocs-material 9.5.39

설치는 pip install mkdocs-material 한 줄이며, 이 PC에는 이미 설치되어 있어 설치 과정은 실행하지 않았습니다.

1. 파일 구성

site-src/
  mkdocs.yml
  docs/
    index.md
    runbook.md
site_name: Team Notes
theme:
  name: material
  language: ko
nav:
  - Home: index.md
  - Runbook: runbook.md
markdown_extensions:
  - admonition
  - tables

runbook.md에는 경고 상자(!!! warning)와 표, 그리고 없는 문서로 일부러 건 링크(missing.md)를 넣었습니다.

이 단계의 파일 내려받기:mkdocs.yml

2. 빌드

python -m mkdocs build
# 기대 출력(이 PC)
WARNING -  Doc file 'runbook.md' contains a link 'missing.md', but the target is not found among documentation files.
INFO    -  Documentation built in 1.80 seconds

site/ 폴더에 index.html, runbook/, search/, sitemap.xml, 404.html과 assets/가 생겼고 크기는 2.5MB였습니다. 테마 파일이 대부분이라 두 쪽짜리 문서인데도 용량이 큽니다. 경고 상자는 HTML에서 admonition warning 클래스로 한 번 나타났습니다.

MkDocs Material 테마의 Runbook 페이지에서 Warning 상자, 단계와 명령 표, 없는 문서로 건 링크가 보이고 왼쪽 메뉴에 Home과 Runbook이 있는 것을 확인합니다.
MkDocs Material 테마의 Runbook 페이지에서 Warning 상자, 단계와 명령 표, 없는 문서로 건 링크가 보이고 왼쪽 메뉴에 Home과 Runbook이 있는 것을 확인합니다.

이 단계의 파일 내려받기:mkdocs.yml

3. 깨진 링크를 오류로 만들기

경고는 빌드를 막지 않아서, 그대로 두면 깨진 링크가 배포됩니다. --strict를 붙이면 경고가 오류가 됩니다.

python -m mkdocs build --strict ; echo $?
# 기대 출력
1

종료 코드가 1이었습니다. 문서 저장소의 CI에서 이 명령을 돌리면 링크 오류가 있는 변경을 병합 전에 막을 수 있습니다. 링크를 고치면 0이 되는지는 이 글에서 확인하지 않았습니다.

mkdocs build --strict가 missing.md 링크 경고를 출력한 뒤 Aborted with 1 warnings in strict mode로 끝나고 종료 코드 1이 찍히는 것을 확인합니다.
mkdocs build --strict가 missing.md 링크 경고를 출력한 뒤 Aborted with 1 warnings in strict mode로 끝나고 종료 코드 1이 찍히는 것을 확인합니다.

이 단계의 파일 내려받기:mkdocs.yml

4. 로컬 미리보기

python -m mkdocs serve -a 127.0.0.1:8765

http://127.0.0.1:8765/runbook/가 HTTP 200으로 열렸습니다. 이 서버는 파일을 저장하면 다시 빌드하는 개발용이므로 운영 서비스로 쓰지 않고, 확인 뒤 종료했습니다.

브라우저로 연 첫 페이지에서 Team Notes 제목 표시줄과 검색 상자, 왼쪽 메뉴, 본문 안내 문장과 런북 링크가 보이는 것을 확인합니다.
브라우저로 연 첫 페이지에서 Team Notes 제목 표시줄과 검색 상자, 왼쪽 메뉴, 본문 안내 문장과 런북 링크가 보이는 것을 확인합니다.

이 단계의 파일 내려받기:mkdocs.yml

더 해 보기: 경고 상자와 탭, 밝은 테마와 어두운 테마, 엄격 빌드가 잡는 것

위에서는 두 쪽짜리 문서를 만들고 --strict로 깨진 링크 하나를 잡았습니다. 실제 팀 문서에는 경고 상자, 접는 설명, 운영체제별 탭, 어두운 테마가 필요하고, 문서가 늘면 깨지는 곳도 다양해집니다. 이 모두를 쓰는 작은 문서(세 쪽)를 만들어 빌드하고, 엄격 빌드가 무엇을 잡고 무엇을 놓치는지 확인했습니다(mkdocs_more.py). 프로젝트는 임시 폴더에 만들고 끝에서 지웁니다.

설정 추가

mkdocs.yml에 아래를 더했습니다.

설정 역할
markdown_extensions: admonition !!! note 같은 경고 상자
pymdownx.details ???로 접어 두는 설명
pymdownx.superfences, pymdownx.tabbed 코드 블록과 === "리눅스" 탭
theme.palette 두 항목 브라우저 설정에 따른 밝은 테마(default)와 어두운 테마(slate) 선택, 화면의 단추로 전환
theme.features: content.code.copy 등 코드 복사 단추, 검색 제안
nav 목차 순서와 묶음(처음, 운영 아래 두 쪽)
validation: anchors: warn 문서 안의 #제목 링크가 가리키는 제목이 없으면 경고

빌드 결과

항목 값
엄격 빌드 종료 코드 0 (경고 없음)
만들어진 파일 50개, 합계 2,451KB
검색 색인 항목 5개
첫 쪽의 경고 상자 구조 4개(안내, 주의, 접기 외 하나는 무엇인지 확인하지 않음)
접기, 탭 묶음 각각 1개
테마 값 default와 slate 둘 다 들어 있음

세 쪽짜리 문서인데 파일이 50개, 2.4MB입니다. 대부분은 테마가 만든 스크립트, 스타일, 글꼴, 아이콘이며 직접 쓴 글이 차지하는 용량은 작습니다. 정적 파일이라 웹 서버 폴더에 그대로 올리면 됩니다. 코드 복사 단추는 서버가 만든 HTML에는 없고 브라우저에서 스크립트가 붙이므로, 빌드 결과 파일의 글자 수로는 셀 수 없었습니다.

실제 화면

빌드한 사이트를 127.0.0.1에 잠깐 열어 자동화된 브라우저로 찍었습니다. 브라우저의 화면 선호(밝게, 어둡게)에 따라 페이지의 테마가 default와 slate로 바뀌는 것도 확인했습니다. 설정에서 prefers-color-scheme을 쓰도록 했기 때문입니다.

밝은 테마의 첫 쪽에서 팀 문서 제목 아래에 파란 안내 상자, 주황 주의 상자, 접힌 설명, 리눅스와 윈도우 탭의 코드 블록, 담당 표가 보이는 것을 확인합니다.
밝은 테마의 첫 쪽에서 팀 문서 제목 아래에 파란 안내 상자, 주황 주의 상자, 접힌 설명, 리눅스와 윈도우 탭의 코드 블록, 담당 표가 보이는 것을 확인합니다.

어두운 테마의 같은 쪽에서 상자와 탭과 표가 어두운 배경에 같은 구성으로 보이고, 오른쪽 위에 테마를 바꾸는 단추가 있는 것을 확인합니다.
어두운 테마의 같은 쪽에서 상자와 탭과 표가 어두운 배경에 같은 구성으로 보이고, 오른쪽 위에 테마를 바꾸는 단추가 있는 것을 확인합니다.

엄격 빌드가 잡는 것과 놓치는 것

일부러 망가뜨린 세 가지를 --strict로 빌드했습니다.

망가뜨린 것 종료 코드 결과
없는 페이지로 링크(nothing.md) 1 경고 1건으로 중단
없는 제목으로 링크(deploy.md#없는제목) 1 경고 1건으로 중단(validation: anchors: warn 덕분)
nav에 없는 파일 이름 1 경고 2건으로 중단

세 가지 모두 잡혔습니다. 그런데 같은 첫 번째 오류에 --quiet을 더하면 종료 코드가 0이 되었습니다. --quiet은 경고 메시지를 숨기는 옵션인데, 엄격 검사도 숨겨진 경고는 세지 않아서 오류가 있는 문서가 통과합니다. 빌드 로그를 조용하게 하려고 --quiet을 CI 명령에 무심코 붙이면 엄격 검사가 무력해집니다. --strict는 --quiet 없이 씁니다. 이 한 가지가 이 절에서 가장 실용적인 발견입니다.

또 하나 알아 둘 것은 anchors 검사가 기본이 아니라는 점입니다. 설정에서 validation: anchors: warn을 켜야 없는 제목 링크를 잡았습니다. 이 설정이 없으면 없는 제목으로 가는 링크는 조용히 통과하는 것으로 추정하지만, 설정을 뺀 빌드는 이 글에서 시험하지 않았습니다.

mkdocs_more.py 실행 결과에서 엄격 빌드가 통과하고, 파일 50개와 검색 색인 5개, 경고 상자 4개가 나오며, 망가뜨린 세 가지가 모두 종료 코드 1이고 --quiet을 더하면 0이 되며, 브라우저의 밝게와 어둡게 선호가 default와 slate 테마로 이어지는 것을 확인합니다.
mkdocs_more.py 실행 결과에서 엄격 빌드가 통과하고, 파일 50개와 검색 색인 5개, 경고 상자 4개가 나오며, 망가뜨린 세 가지가 모두 종료 코드 1이고 --quiet을 더하면 0이 되며, 브라우저의 밝게와 어둡게 선호가 default와 slate 테마로 이어지는 것을 확인합니다.

mkdocs_more.py는 아래와 같습니다. 화면 캡처는 playwright와 크롬이 있을 때만 됩니다.

"""MkDocs Material 심화: 확장 기능(경고 상자, 탭, 접기, 코드 복사), 밝은/어두운 테마, 검색 색인, 엄격 빌드가 잡는 오류, 화면 캡처.

준비: pip install mkdocs mkdocs-material playwright (그리고 크롬 또는 playwright install chromium)
주의: 임시 폴더에 프로젝트를 만들어 빌드하고 끝에서 지운다. 화면 캡처는 이 PC의 127.0.0.1:8765 에 잠깐 서버를 띄운다.
실행: python -X utf8 mkdocs_more.py [캡처를 저장할 폴더]   (약 40초)
"""
import json
import os
import shutil
import subprocess
import sys
import tempfile
import threading
import functools
import http.server

from playwright.sync_api import sync_playwright

SHOTS = sys.argv[1] if len(sys.argv) > 1 else None
root = tempfile.mkdtemp(prefix="mk-")
os.makedirs(os.path.join(root, "docs", "ops"))

CFG = """site_name: Team Notes
theme:
  name: material
  language: ko
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle: {icon: material/weather-night, name: 어두운 테마로}
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle: {icon: material/weather-sunny, name: 밝은 테마로}
  features: [content.code.copy, navigation.sections, search.suggest, toc.follow]
nav:
  - 처음: index.md
  - 운영:
      - 배포 절차: ops/deploy.md
      - 장애 대응: ops/runbook.md
markdown_extensions:
  - admonition
  - tables
  - toc: {permalink: true}
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed: {alternate_style: true}
validation:
  anchors: warn
"""
INDEX = """# 팀 문서

!!! note "이 문서는"
    팀 운영 절차를 모아 둡니다. 수정은 `docs/` 폴더의 마크다운을 고치면 됩니다.

!!! warning "주의"
    운영 서버에서 직접 명령을 실행하기 전에 [배포 절차](ops/deploy.md)를 먼저 읽습니다.

??? tip "접어 둔 설명(눌러서 펼침)"
    자주 묻는 질문은 이곳에 모읍니다.

=== "리눅스"
    ```bash
    sudo systemctl restart app
    ```
=== "윈도우"
    ```powershell
    Restart-Service app
    ```

| 구분 | 담당 | 연락 |
|---|---|---|
| 배포 | 운영팀 | 내선 101 |
| 장애 | 보안팀 | 내선 202 |
"""
DEPLOY = "# 배포 절차\n\n## 준비\n\n1. 변경 내용을 확인합니다.\n\n## 실행\n\n명령을 실행합니다.\n"
RUNBOOK = "# 장애 대응\n\n[배포 절차의 실행 단계](deploy.md#실행)를 따릅니다.\n"
for name, text in (("mkdocs.yml", CFG), ("docs/index.md", INDEX), ("docs/ops/deploy.md", DEPLOY), ("docs/ops/runbook.md", RUNBOOK)):
    open(os.path.join(root, name), "w", encoding="utf-8", newline="\n").write(text)


def mk(*a):
    r = subprocess.run([sys.executable, "-X", "utf8", "-m", "mkdocs", *a], cwd=root, capture_output=True, text=True, encoding="utf-8")
    return r.returncode, (r.stdout + r.stderr)


print("## 1. 엄격 빌드(--strict)")
code, out = mk("build", "--strict", "--quiet")
print(f"  종료 코드 {code}", "(경고도 오류로 보는 상태에서 통과)" if code == 0 else out[:200])

site = os.path.join(root, "site")
files = [os.path.join(d, f) for d, _, fs in os.walk(site) for f in fs]
size = sum(os.path.getsize(f) for f in files)
idx = json.load(open(os.path.join(site, "search", "search_index.json"), encoding="utf-8"))
html = open(os.path.join(site, "index.html"), encoding="utf-8").read()
print(f"\n## 2. 빌드 결과: 파일 {len(files)}개, 합계 {size / 1024:.0f}KB, 검색 색인 항목 {len(idx['docs'])}개")
print(f"  경고 상자 {html.count('class=\"admonition')}개, 접기 {html.count('<details')}개, 탭 묶음 {html.count('tabbed-set')}개")
print(f"  밝은/어두운 테마 표시: scheme 값 {sorted(set(__import__('re').findall(r'data-md-color-scheme=\"(\w+)\"', html)))}")

print("\n## 3. 일부러 망가뜨린 세 가지를 --strict 가 잡는가")
cases = {
    "없는 페이지로 링크": ("docs/ops/runbook.md", "# 장애 대응\n\n[없는 글](nothing.md)\n"),
    "없는 제목(#앵커)으로 링크": ("docs/ops/runbook.md", "# 장애 대응\n\n[배포](deploy.md#없는제목)\n"),
    "nav 에 없는 파일 이름": ("mkdocs.yml", CFG.replace("ops/runbook.md", "ops/missing.md")),
}
good_runbook = RUNBOOK
for label, (path, text) in cases.items():
    open(os.path.join(root, path), "w", encoding="utf-8", newline="\n").write(text)
    code, out = mk("build", "--strict")
    line = next((l for l in out.splitlines() if "WARNING" in l or "ERROR" in l or "Aborted" in l), "").strip()
    print(f"  {label:<24} 종료 코드 {code} | {line[:70]}")
    if label.startswith("없는 페이지"):
        code_q, _ = mk("build", "--strict", "--quiet")
        print(f"    같은 오류에 --quiet 을 더하면 종료 코드 {code_q} (경고가 숨겨져 엄격 검사가 통과해 버림)")
    open(os.path.join(root, "docs/ops/runbook.md"), "w", encoding="utf-8", newline="\n").write(good_runbook)
    open(os.path.join(root, "mkdocs.yml"), "w", encoding="utf-8", newline="\n").write(CFG)

print("\n## 4. 화면 캡처(밝은 테마와 어두운 테마)")
mk("build", "--quiet")
class Quiet(http.server.SimpleHTTPRequestHandler):
    def log_message(self, *a):
        pass


handler = functools.partial(Quiet, directory=site)
srv = http.server.ThreadingHTTPServer(("127.0.0.1", 8765), handler)
threading.Thread(target=srv.serve_forever, daemon=True).start()
with sync_playwright() as p:
    b = p.chromium.launch(channel="chrome", headless=True)
    for scheme in ("light", "dark"):
        pg = b.new_page(viewport={"width": 1100, "height": 760}, color_scheme=scheme)
        pg.goto("http://127.0.0.1:8765/", wait_until="load")
        pg.wait_for_timeout(800)
        got = pg.evaluate("document.body.getAttribute('data-md-color-scheme')")
        if SHOTS:
            os.makedirs(SHOTS, exist_ok=True)
            pg.screenshot(path=os.path.join(SHOTS, f"{'03' if scheme == 'light' else '04'}-페이지-{scheme}.png"))
        print(f"  브라우저 선호 {scheme:<5} -> 페이지의 data-md-color-scheme = {got}")
    b.close()
srv.shutdown()
shutil.rmtree(root, ignore_errors=True)
print("  임시 폴더와 서버 정리 완료")
이 단계의 파일 내려받기:mkdocs.ymlmkdocs_more.py

전체 코드

아래 세 파일이 이 글의 사이트 전부입니다. 아래 구조로 저장하고 python -m mkdocs build, python -m mkdocs build --strict, python -m mkdocs serve를 차례로 실행합니다.

site-src/
  mkdocs.yml
  docs/
    index.md
    runbook.md

mkdocs.yml

site_name: Team Notes
theme:
  name: material
  language: ko
nav:
  - Home: index.md
  - Runbook: runbook.md
markdown_extensions:
  - admonition
  - tables

docs/index.md

# Team Notes

팀 문서 시작 페이지입니다. [런북](runbook.md)을 참고하세요.

docs/runbook.md

# Runbook

!!! warning
    운영 서버 재시작 전에 담당자에게 알립니다.

| 단계 | 명령 |
|---|---|
| 상태 확인 | `docker ps` |
| 재시작 | `docker restart app` |

링크 오류 예시: [없는 문서](missing.md)
이 단계의 파일 내려받기:mkdocs.yml

자주 막히는 곳

증상 원인과 해결
Theme 'material' unrecognised mkdocs-material 미설치
한글 파일명 링크가 깨짐 파일명과 링크 철자를 맞춘 뒤 --strict로 확인
serve가 종료되지 않음 터미널에서 Ctrl+C로 종료. 백그라운드로 띄웠다면 프로세스를 직접 종료

확인 범위

  • 해 본 것: 2026-10-29에 mkdocs_more.py로 확장 기능과 테마를 더한 세 쪽짜리 문서를 빌드하고, 망가뜨린 세 가지와 --quiet의 영향, 밝은/어두운 화면을 확인했습니다. 앞의 확인 내용은 다음과 같습니다. 2026-10-28, Windows 11 · Python 3.12.10 · MkDocs 1.6.1 · Material 9.5.39에서 위 두 문서를 빌드, --strict 빌드, serve로 한 번씩 실행했습니다.
  • 해 보지 않은 것: 검색 기능 동작과 한국어 검색 품질, 공개 서버 배포(GitHub Pages 등), 검색 외 플러그인, 다중 버전 문서, 링크 수정 후 --strict 통과.
  • 읽을 때 주의: 화면은 mkdocs serve로 띄운 페이지를 자동화된 브라우저로 캡처한 것입니다. 검색 기능과 모바일 화면은 확인하지 않았습니다.
이 단계의 파일 내려받기:mkdocs_more.py

이 글의 다음 단계

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글