Hugo로 매뉴얼 만들기 #3 콘텐츠 작성 — 코드블록, Mermaid, 콜아웃

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

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

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

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

이번 글은 코드블록을 제대로 꾸미고, Mermaid로 다이어그램을 그리고, 콜아웃으로 강조하는 세 가지를 다루겠습니다. 모두 표준 마크다운에 Hextra가 얹어 주는 기능입니다.

코드블록 — 파일명과 줄 강조 #

가장 기본은 펜스로 감싼 코드블록입니다. 여기에 Hextra는 몇 가지를 더해 줍니다. 코드 펜스의 언어 뒤에 중괄호로 옵션을 적습니다.

코드블록에 파일명 달기 
```js {filename="main.js"}
console.log("hello");
```

이렇게 적으면 코드블록 위에 main.js라는 파일명 띠가 붙습니다. 어느 파일의 코드인지 한눈에 보이므로, 여러 파일을 오가는 설명에서 특히 유용합니다.

특정 줄을 강조하거나 줄 번호를 붙일 수도 있습니다.

줄 강조와 줄 번호 
```py {filename="app.py",hl_lines=[2],linenos=table}
def add(a, b):
    return a + b  # 이 줄이 강조됩니다
```

hl_lines로 강조할 줄을, linenos=table로 줄 번호를 지정합니다. 복사 버튼은 Hextra가 모든 코드블록에 자동으로 붙여 주므로 따로 손댈 것이 없습니다.

다이어그램 — Mermaid #

아키텍처나 흐름을 설명할 때 이미지를 직접 그려 넣으면, 나중에 수정할 때마다 이미지 파일을 다시 만들어야 합니다. Mermaid는 다이어그램을 코드로 적습니다. 텍스트라 Git으로 버전 관리가 되고, 고치기도 쉽습니다. mermaid 언어로 펜스를 열면 됩니다.

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

Hextra는 이 블록을 빌드 시점에 실제 다이어그램으로 렌더합니다. 흐름도뿐 아니라 시퀀스 다이어그램, 클래스 다이어그램, 간트 차트 등 Mermaid가 지원하는 형식을 그대로 쓸 수 있습니다.

콜아웃 — 주의와 경고 강조 #

“이건 꼭 읽어야 한다"는 내용은 줄글 사이에 묻히면 안 됩니다. Hextra는 callout 셋코드(shortcode)로 강조 상자를 제공합니다.

콜아웃 쓰기 
{{< callout type="warning" >}}
프로덕션에 적용하기 전에 반드시 백업을 먼저 하세요.
{{< /callout >}}

type에는 info, warning, error를 줄 수 있고, 생략하면 기본 회색 상자가 됩니다. 각 타입마다 색과 아이콘이 달라, 정보, 주의, 위험을 시각적으로 구분할 수 있습니다.

참고로 위 예시처럼 셋코드를 코드블록 안에 그대로 보여 주려면 Hugo의 이스케이프 표기 {{< >}}를 써야 합니다. 그냥 적으면 Hugo가 셋코드를 실행해 버려서, 코드 예시가 아니라 진짜 콜아웃이 렌더됩니다. 문서를 쓰다 자주 밟는 함정이라 #6에서 다시 정리하겠습니다.

그 밖의 블록 — 탭과 스텝 #

긴 설명을 접거나 운영체제별로 나눠 보여 줄 때는 탭이 편합니다.

탭으로 나누기 
{{< tabs items="macOS, Windows" >}}
  {{< tab >}}brew install ...{{< /tab >}}
  {{< tab >}}winget install ...{{< /tab >}}
{{< /tabs >}}

설치처럼 순서가 중요한 절차는 steps로 번호를 매겨 보여 줄 수 있습니다. 이런 셋코드들은 Hextra에 기본 내장되어 있어, 추가 설치 없이 바로 쓰면 됩니다.

마무리 #

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

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

X