MkDocs Material 개발 환경 Runbook (Windows)¶

이 문서는 현재 프로젝트의 MkDocs Material 문서 사이트를 Windows 로컬 환경에서 작성, 실행, 검증하기 위한 runbook이다.

기준은 이 문서가 아니라 현재 프로젝트의 실제 구성이다.

1. 적용 범위¶

대상 프로젝트: GitLab에서 클론한 프로젝트 루트
MkDocs 설정 파일: mkdocs.yml
문서 루트: docs/
빌드 출력 경로: site/
최종 검증 기준: mkdocs build --strict

Markdown Preview Enhanced 같은 에디터 미리보기는 작성 보조 도구일 뿐이다.
최종 판단은 반드시 MkDocs 빌드 결과와 로컬 서버 화면으로 한다.

2. 현재 프로젝트 기준 구성¶

현재 mkdocs.yml 기준으로 이 프로젝트는 다음 구성을 사용한다.

항목	현재 기준
대상 프로젝트	GitLab에서 클론한 프로젝트 루트
사이트 이름	`Rocky Linux Production`
테마	`material`
언어	`ko`
문서 디렉터리	`docs`
제외 문서	`07-gitlab-backup/`, `07-gitlab-backup-backup/`, `07-gitlab-lastbackup/`, `98-etc/00-mkdocs-material-dev-setup copy.md`, `999-to-organize/`
추가 CSS	`docs/stylesheets/extra.css`
추가 JavaScript	`docs/javascripts/mermaid.min.js`, `docs/javascripts/mermaid.js`
Mermaid	`pymdownx.superfences.custom_fences` 기준
내비게이션	`mkdocs.yml`의 `nav`를 명시적으로 관리

현재 프로젝트에는 Python 의존성 고정 파일(requirements.txt, pyproject.toml)이 없다.
따라서 이 runbook은 현재 구조에 맞춰 로컬 Python 환경에 필요한 패키지를 설치하는 방식으로 작성한다.

3. 사전 조건 확인¶

PowerShell을 열고 프로젝트 루트로 이동한다.

$PROJECT_ROOT = "<GitLab에서 클론한 프로젝트 경로>"
Set-Location $PROJECT_ROOT

Python과 pip가 동작하는지 확인한다.

python --version
python -m pip --version

정상 기준:

Python 버전이 출력됨
pip 버전이 출력됨
명령 실행 위치가 GitLab에서 클론한 프로젝트 루트임

Python이 없거나 명령을 찾지 못하면 Python 64bit 버전을 설치하고, 설치 시 Add Python to PATH를 활성화한다.

4. MkDocs 실행 환경 준비¶

최초 클론 후 Python 패키지 설치 기준은 프로젝트 루트 README.md를 따른다.

현재 mkdocs.yml은 pymdownx.* 확장을 사용하므로 설치 상태를 확인한다.

python -m pip show mkdocs-material pymdown-extensions
python -m mkdocs --version

pymdown-extensions가 누락된 경우만 별도로 설치한다.

python -m pip install --upgrade pymdown-extensions

5. Shared Assets 심링크 준비¶

GitLab에서 로컬로 클론한 뒤에는 docs와 docs-runbook이 함께 쓰는 CSS/JavaScript 경로를 심링크로 연결한다.

실행 방법:

scripts\setup-mkdocs-shared-assets.cmd를 더블클릭한다.
scripts\setup-mkdocs-shared-assets.cmd를 마우스 오른쪽 버튼으로 선택한 뒤 관리자 권한으로 실행한다.
프로젝트 루트에서 아래 명령으로 실행한다.

.\scripts\setup-mkdocs-shared-assets.cmd

.cmd 실행기는 일반 실행과 관리자 권한 실행을 모두 처리한다. 일반 실행 중 심링크 생성 권한이 필요하면 UAC 승격을 요청한다.

이미 관리자 권한 PowerShell을 사용 중이면 직접 실행할 수 있다.

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup-mkdocs-shared-assets.ps1

정상 기준:

docs/stylesheets와 docs/javascripts가 프로젝트 루트의 stylesheets, javascripts를 가리킴
docs-runbook/stylesheets와 docs-runbook/javascripts도 같은 대상을 가리킴

6. 프로젝트 파일 확인¶

다음 파일이 있어야 한다.

Test-Path .\mkdocs.yml
Test-Path .\docs\README.md
Test-Path .\docs\stylesheets\extra.css
Test-Path .\docs\javascripts\mermaid.min.js
Test-Path .\docs\javascripts\mermaid.js

정상 기준:

모든 명령이 True를 출력함
누락 파일이 있으면 mkdocs.yml의 extra_css, extra_javascript, nav와 실제 파일 구조를 먼저 맞춤

7. 문서 작성 절차¶

문서는 반드시 docs/ 하위에 Markdown 파일로 작성한다.

새 문서를 추가할 때의 기준:

파일을 docs/ 하위의 적절한 카테고리에 생성한다.
파일명은 번호와 역할이 드러나도록 작성한다.
사이트 메뉴에 노출할 문서는 mkdocs.yml의 nav에 추가한다.
메뉴에 노출하지 않을 백업성 문서는 exclude_docs 대상인지 확인한다.
코드 블록에는 가능한 한 언어를 명시한다.
Mermaid 다이어그램은 fenced code block의 언어를 mermaid로 지정한다.

Mermaid 예시:

```mermaid
flowchart TD
    A[Edit Markdown] --> B[Build]
    B --> C[Serve]
```

8. 로컬 빌드 검증¶

문서 변경 후 반드시 strict 빌드를 실행한다.

python -m mkdocs build --strict -f mkdocs.yml

정상 기준:

Documentation built 메시지가 출력됨
warning 없이 종료됨
site/ 디렉터리에 정적 사이트가 생성됨

--strict에서 warning이 발생하면 실패로 간주하고 원인을 수정한다.
warning을 무시한 상태로 문서 변경을 완료하지 않는다.

9. 로컬 서버 실행¶

빌드가 통과하면 로컬 서버로 실제 화면을 확인한다.

python -m mkdocs serve -f mkdocs.yml -a 127.0.0.1:8000

브라우저에서 접속한다.

http://127.0.0.1:8000/

확인 기준:

Home 페이지가 정상 표시됨
좌측 내비게이션이 mkdocs.yml의 nav 순서대로 표시됨
코드 블록 복사 버튼이 표시됨
Mermaid 다이어그램이 필요한 문서에서 정상 렌더링됨
한글 검색과 페이지 이동이 정상 동작함

8000 포트가 이미 사용 중이면 다른 포트를 사용한다.

python -m mkdocs serve -f mkdocs.yml -a 127.0.0.1:8001

mkdocs 명령이 인식되는 환경에서는 다음처럼 실행해도 된다.

mkdocs serve -f mkdocs.yml

10. VSCode 사용 기준¶

VSCode는 문서 작성 편의 도구로만 사용한다.

현재 프로젝트의 .vscode/settings.json에는 다음 정도의 최소 설정만 있다.

{
    "markdown.validate.enabled": false,
    "explorer.sortOrder": "mixed"
}

권장 확장:

Markdown All in One
Markdown Preview Enhanced

주의 사항:

VSCode 미리보기 결과를 최종 기준으로 삼지 않는다.
Material 테마, Mermaid, 내비게이션, 검색 동작은 mkdocs serve 화면에서 확인한다.
수동 목차를 문서마다 강제로 넣지 않는다. 페이지 내 목차는 MkDocs가 헤더 기준으로 생성한다.

11. 문제 대응¶

11.1 `No module named mkdocs`¶

MkDocs Material을 다시 설치한다.

python -m pip install --upgrade mkdocs-material
python -m mkdocs --version

11.2 `pymdownx` 확장 로드 실패¶

현재 mkdocs.yml은 pymdownx.highlight, pymdownx.superfences, pymdownx.details, pymdownx.tasklist, pymdownx.tabbed를 사용한다.

python -m pip install --upgrade pymdown-extensions
python -m mkdocs build --strict -f mkdocs.yml

11.3 Mermaid가 렌더링되지 않음¶

다음을 확인한다.

Test-Path .\docs\javascripts\mermaid.min.js
Test-Path .\docs\javascripts\mermaid.js

그리고 mkdocs.yml에 다음 구성이 유지되어야 한다.

extra_javascript:
  - javascripts/mermaid.min.js
  - javascripts/mermaid.js

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

11.4 nav 경로 오류¶

mkdocs.yml의 nav에 등록된 경로는 docs/ 기준 상대 경로다.

예시:

nav:
  - Home: README.md
  - '98 - Etc':
      - '00 - MkDocs Material 개발 환경 설정 (Windows)': 98-etc/00-mkdocs-material-dev-setup.md

실제 파일이 없거나 경로 대소문자가 다르면 mkdocs build --strict에서 실패할 수 있다.

11.5 포트 충돌¶

기본 포트 8000이 사용 중이면 포트를 바꿔 실행한다.

python -m mkdocs serve -f mkdocs.yml -a 127.0.0.1:8001

12. 완료 기준¶

문서 작업은 다음 조건을 모두 만족해야 완료로 본다.

python -m mkdocs build --strict -f mkdocs.yml 성공
python -m mkdocs serve -f mkdocs.yml -a 127.0.0.1:8000 또는 대체 포트에서 화면 확인
추가/수정 문서가 필요한 경우 mkdocs.yml의 nav에 반영
Mermaid, CSS, JavaScript 관련 파일 경로가 실제 프로젝트와 일치
site/ 산출물을 직접 수정하지 않음

MkDocs Material 개발 환경 Runbook (Windows)¶

1. 적용 범위¶

2. 현재 프로젝트 기준 구성¶

3. 사전 조건 확인¶

4. MkDocs 실행 환경 준비¶

5. Shared Assets 심링크 준비¶

6. 프로젝트 파일 확인¶

7. 문서 작성 절차¶

8. 로컬 빌드 검증¶

9. 로컬 서버 실행¶

10. VSCode 사용 기준¶

11. 문제 대응¶

11.1 No module named mkdocs¶

11.2 pymdownx 확장 로드 실패¶

11.3 Mermaid가 렌더링되지 않음¶

11.4 nav 경로 오류¶

11.5 포트 충돌¶

12. 완료 기준¶

11.1 `No module named mkdocs`¶

11.2 `pymdownx` 확장 로드 실패¶