MkDocs로 매뉴얼 만들기 #3 콘텐츠 작성 — 코드블록, Mermaid, admonition

프레임워크 MkDocs Documentation Static Site
3 분 소요

#2에서 nav와 검색으로 문서의 뼈대를 잡았습니다. 이제 그 안을 채울 차례입니다. 기술 문서는 줄글만으로는 부족합니다. 명령은 코드블록으로, 흐름은 다이어그램으로, 주의할 점은 눈에 띄는 상자로 보여 줘야 독자가 빠르게 읽습니다.

이번 시리즈는 MkDocs로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 nav와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, admonition ← 이번 글
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 코드블록을 제대로 꾸미고, Mermaid로 다이어그램을 그리고, admonition으로 강조하는 세 가지를 다루겠습니다. 이 기능들은 대부분 마크다운 확장으로 켜므로, 먼저 그것부터 설정합니다.

마크다운 확장 켜기 #

Material의 풍부한 표현은 pymdownx 확장에서 나옵니다. mkdocs.yml에 필요한 확장을 등록합니다.

mkdocs.yml — 마크다운 확장 
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

theme:
  name: material
  features:
    - content.code.copy   # 코드블록 복사 버튼

코드블록 — 제목과 줄 강조 #

코드 펜스의 언어 뒤에 옵션을 적어 제목과 강조를 더합니다.

코드블록에 제목 달기 
```python title="app.py" hl_lines="2" linenums="1"
def add(a, b):
    return a + b  # 이 줄이 강조됩니다
```

title로 파일명 띠를, hl_lines로 강조할 줄을, linenums로 줄 번호를 지정합니다. 복사 버튼은 위에서 켠 content.code.copy 기능이 모든 코드블록에 자동으로 붙여 줍니다.

다이어그램 — Mermaid #

Mermaid는 다이어그램을 코드로 적습니다. 텍스트라 Git으로 버전 관리가 되고 고치기도 쉽습니다. MkDocs에서는 superfences에 Mermaid를 등록하면 됩니다.

mkdocs.yml — Mermaid 활성화 
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

이제 mermaid 펜스를 열면 실제 다이어그램으로 렌더됩니다.

Mermaid 흐름도 
```mermaid
flowchart LR
  A[글 작성] --> B[빌드] --> C[배포]
```

admonition — 주의와 경고 강조 #

“이건 꼭 읽어야 한다"는 내용은 줄글 사이에 묻히면 안 됩니다. admonition은 강조 상자를 만듭니다. !!! 뒤에 종류를 적고, 내용을 들여쓰기로 넣습니다.

admonition 쓰기 
!!! warning "주의"
    프로덕션에 적용하기 전에 반드시 백업을 먼저 하세요.

종류에는 note, tip, warning, danger 등이 있고, 각각 색과 아이콘이 달라 정보, 주의, 위험을 시각적으로 구분합니다. ???로 적으면 접었다 펴는 상자가 됩니다.

탭으로 나누기 #

운영체제별 명령처럼 갈래가 나뉘는 내용은 탭이 편합니다. 위에서 켠 pymdownx.tabbed로 만듭니다.

탭으로 나누기 
=== "macOS"
    brew install our-product

=== "Windows"
    winget install our-product

마무리 #

이번 글에서는 제목과 줄 강조가 붙는 코드블록, 코드로 관리하는 Mermaid 다이어그램, 그리고 주의, 경고를 강조하는 admonition과 탭까지 다뤘습니다. 여기까지 오면 로컬에서 보기 좋은 문서가 갖춰집니다.

다음 편에서는 이 문서를 세상에 내보냅니다. Cloudflare Pages로 배포하고 커스텀 도메인을 연결해, 누구나 주소로 접속할 수 있게 만드는 과정을 정리하겠습니다.

X