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

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

- 주소: https://copyandrun.com/blog/mkdocs-material-team-docs-site/
- 분야: AX
- 발행일: 2026-10-28
- 태그: MkDocs, Material for MkDocs, 문서화, 마크다운

팀 문서가 메신저와 개인 폴더에 흩어져 있으면 최신 판을 찾기 어렵습니다. 마크다운 파일을 저장소에 두고 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
```

```yaml
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`)를 넣었습니다.

## 2. 빌드

<!-- files: mkdocs.yml -->

```bash
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이 있는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/02-런북-경고-상자-표.png)

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

<!-- files: mkdocs.yml -->

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

```bash
python -m mkdocs build --strict ; echo $?
```

```
# 기대 출력
1
```

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

![mkdocs build --strict가 missing.md 링크 경고를 출력한 뒤 Aborted with 1 warnings in strict mode로 끝나고 종료 코드 1이 찍히는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/01-strict-빌드.png)

## 4. 로컬 미리보기

<!-- files: mkdocs.yml -->

```bash
python -m mkdocs serve -a 127.0.0.1:8765
```

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

![브라우저로 연 첫 페이지에서 Team Notes 제목 표시줄과 검색 상자, 왼쪽 메뉴, 본문 안내 문장과 런북 링크가 보이는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/01-첫-페이지.png)

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

위에서는 두 쪽짜리 문서를 만들고 `--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`을 쓰도록 했기 때문입니다.

![밝은 테마의 첫 쪽에서 팀 문서 제목 아래에 파란 안내 상자, 주황 주의 상자, 접힌 설명, 리눅스와 윈도우 탭의 코드 블록, 담당 표가 보이는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/03-페이지-light.png)

![어두운 테마의 같은 쪽에서 상자와 탭과 표가 어두운 배경에 같은 구성으로 보이고, 오른쪽 위에 테마를 바꾸는 단추가 있는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/04-페이지-dark.png)

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

일부러 망가뜨린 세 가지를 `--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 테마로 이어지는 것을 확인합니다.](https://copyandrun.com/img/mkdocs-material-team-docs-site/05-빌드-엄격-테마.png)

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

````python
"""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("  임시 폴더와 서버 정리 완료")
````

## 전체 코드

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

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

`mkdocs.yml`

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

`docs/index.md`

```markdown
# Team Notes

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

`docs/runbook.md`

```markdown
# Runbook

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

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

링크 오류 예시: [없는 문서](missing.md)
```

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `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`로 띄운 페이지를 자동화된 브라우저로 캡처한 것입니다. 검색 기능과 모바일 화면은 확인하지 않았습니다.
