팀 문서가 메신저와 개인 폴더에 흩어져 있으면 최신 판을 찾기 어렵습니다. 마크다운 파일을 저장소에 두고 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)를 넣었습니다.
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 클래스로 한 번 나타났습니다.

3. 깨진 링크를 오류로 만들기
경고는 빌드를 막지 않아서, 그대로 두면 깨진 링크가 배포됩니다. --strict를 붙이면 경고가 오류가 됩니다.
python -m mkdocs build --strict ; echo $?
# 기대 출력
1
종료 코드가 1이었습니다. 문서 저장소의 CI에서 이 명령을 돌리면 링크 오류가 있는 변경을 병합 전에 막을 수 있습니다. 링크를 고치면 0이 되는지는 이 글에서 확인하지 않았습니다.

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

더 해 보기: 경고 상자와 탭, 밝은 테마와 어두운 테마, 엄격 빌드가 잡는 것
위에서는 두 쪽짜리 문서를 만들고 --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는 아래와 같습니다. 화면 캡처는 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(" 임시 폴더와 서버 정리 완료")
전체 코드
아래 세 파일이 이 글의 사이트 전부입니다. 아래 구조로 저장하고 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)
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
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로 띄운 페이지를 자동화된 브라우저로 캡처한 것입니다. 검색 기능과 모바일 화면은 확인하지 않았습니다.
이 글의 다음 단계
- Open WebUI Ollama 연결: host.docker.internal:11434 고치기Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 주소를 localhost로 잘못 넣어 모델 목록이 비는 상태를 만든 뒤 원인을 찾아 고칩니다. 환경 변수를 바로잡아도 저장된 설정이 우선해 되돌아오지 않는 동작도 직접 확인합니다.
- Hermes Agent를 호스트가 아닌 Docker 컨테이너에 설치하고 첫 실행하기명령을 직접 실행하는 오픈소스 에이전트 Hermes Agent를 Ubuntu 컨테이너 안에 설치 스크립트로 설치하고, 첫 실행 화면, hermes doctor 점검, ~/.hermes 데이터 폴더 구조, 웹 대시보드 로그인까지 직접 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com