개요
도구 정보
Hugo로 글을 쓸 때 **대표 이미지(커버/OG 이미지)**를 매번 만드는 일은 부담이 됩니다. 글의 품질이 아니라 디자인 작업에 시간이 쓰이고, 스타일이 글마다 달라지면 사이트 일관성도 깨집니다. 소셜 공유(Open Graph)에서도 눈에 덜 띄게 됩니다.
이 레포에는 JSON 스펙 기반으로 대표 이미지를 자동 생성하는 스크립트가 포함되어 있습니다.
| 항목 | 내용 |
|---|---|
| 생성기 | script/hero_infographic_generator.py |
| 샘플 스펙 | script/hero_infographic_example_spec.json |
| 의존성 | Python 3, Pillow(PIL) |
| 출력 | PNG 이미지(기본 1920×1080, 옵션으로 1200×630 등) |
추천 대상
- Hugo(또는 Jekyll 등 정적 사이트)로 블로그를 운영하며 포스트마다 대표 이미지를 통일하고 싶은 분
- JSON으로 레이아웃을 정의하고 재사용하고 싶은 분
- OG 이미지·카드 미리보기 품질을 올리고 싶은 분
- CLI·스크립트로 이미지 생성을 자동화하고 싶은 분
전체 워크플로우
대표 이미지 생성부터 Hugo에 반영까지의 흐름은 아래와 같습니다.
flowchart LR
subgraph inputGroup[입력]
specFile["JSON 스펙 파일"]
cliArgs["CLI 옵션"]
end
subgraph processGroup[처리]
generator["hero_infographic_generator.py"]
end
subgraph outputGroup[출력]
pngOut["PNG 이미지"]
hugoFront["Hugo front matterimage 필드"]
end
specFile --> generator
cliArgs --> generator
generator --> pngOut
pngOut --> hugoFront
- JSON 스펙으로 헤더·카드·푸터·레이아웃을 정의한다.
- CLI에서 출력 경로와 필요 시
--width,--height,--brand등으로 오버라이드한다. - 생성된 PNG를 포스트 번들에 두고 front matter의
image:에 지정하면 Hugo가 리스트·OG 등에 사용한다.
결과물 예시
아래는 생성기가 만든 대표 이미지 예시입니다(1920×1080).

빠른 시작
1) 기본 생성(스펙 없이)
| |
스펙을 주지 않으면 기본 템플릿으로 생성됩니다(기존 동작과 호환).
2) JSON 스펙으로 생성(추천)
| |
3) 옵션 오버라이드
| |
스펙(JSON) 구조 설명
스펙 파일은 아래 블록으로 구성됩니다. 스펙과 CLI 옵션이 동시에 있으면 CLI가 우선합니다.
flowchart TB
subgraph specBlocks[스펙 블록]
canvas["canvas: width, height"]
header["header: lines, subtitle"]
cards["cards: title, subtitle,accent, bullets"]
footer["footer: text, brand"]
layout["layout: cols"]
typography["typography: bullet_prefix"]
end
canvas --> renderNode
header --> renderNode
cards --> renderNode
footer --> renderNode
layout --> renderNode
typography --> renderNode
renderNode["이미지 렌더링"]
| 블록 | 설명 |
|---|---|
canvas | { "width", "height" } — 캔버스 크기(픽셀) |
header | { "lines": string[], "subtitle"?: string } — 상단 제목·부제 |
cards | 카드 배열. 각 카드: title, subtitle, accent(RGB 배열), bullets(문자열 배열) |
footer | { "text"?: string, "brand"?: string } — 하단 문구·브랜드 |
layout | { "cols" } — 카드 열 수(행은 카드 개수에 따라 자동) |
typography | { "bullet_prefix" } — 글머리 기호 접두어(폰트 깨짐 방지용, 기본 "- ") |
스펙 예시 3개(바로 복사해 쓰기)
아래 예시는 모두 --spec <file.json>으로 사용할 수 있습니다.
예시 1) 비교 2-카드(기본형)

| |
예시 2) 3-카드(Privacy / Anonymity / Pseudonymity)

| |
예시 3) 포스트 템플릿(빈 카드 2개: 빠르게 채우기)

| |
자주 겪는 문제(트러블슈팅)
폰트가 깨져 보인다
- 아이콘·특수문자는 사용 중인 폰트에 없을 수 있습니다.
typography.bullet_prefix기본값은"- "로 두어, 일부 환경에서•등이 깨지는 것을 피합니다.- 한글 폰트를 지정하려면
--font <ttf 경로>를 사용하세요.
텍스트가 박스를 뚫고 나간다
- 공백이 적은 문자열(한글, 긴 영단어)은 줄바꿈이 어렵습니다.
- 생성기는 단어 단위 래핑과 문자 단위 강제 분할 fallback을 사용해 오버플로우를 줄입니다. 그래도 넘치면 카드의
bullets문장을 짧게 나누거나 제목·부제 길이를 조절하는 것이 좋습니다.
스펙 JSON이 로드되지 않는다
- 파일 경로가 올바른지, JSON 문법(쉼표·따옴표)이 맞는지 확인하세요.
- 인코딩은 UTF-8을 권장합니다.
Hugo에 붙이는 패턴
생성한 PNG를 포스트 번들에 두고, front matter의 image:에 파일명만 지정하면 됩니다. Hugo는 이 값을 리스트·상세 페이지·OG/Twitter 카드 등에 사용합니다.
| |
Hugo에서 이미지 메타데이터 사용 방식은 공식 문서의 Front Matter를 참고하면 됩니다.
참고 문헌
- Hugo — Front Matter — Hugo 콘텐츠 메타데이터 및
image등 필드 설명. - Pillow (PIL Fork) Documentation — Python 이미지 처리 라이브러리 Pillow 공식 문서.
- MDN — The metadata element — HTML
meta요소와 OG 등 메타데이터 설명.
한 줄 요약
JSON 스펙 하나로 Hugo 포스트 대표 이미지를 자동 생성하고, front matter image만 지정하면 리스트·OG까지 일관되게 쓸 수 있다.
![Featured image of post [Tool] Hugo 대표 이미지 자동 생성기(hero infographic) 사용법](/post/2025-12-23-hero-infographic-generator-usage/image01_hu_4b5dee44abd06f68.webp)
![[Hardware] LattePanda Alpha에 Ubuntu 16.04 LTS 설치 가이드](/post/2018-12-06-install-ubuntu-16.04-on-lattepanda/wordcloud_hu_fc536f8de2cbd4bf.webp)
![[Rust] Comprehensive Rust 무료 강의 정리 및 코스 구조](/post/2022-12-30-comprehensive-rust/wordcloud_hu_d1420ff38434cdb6.webp)
![[Tutorial] Learn Prompting - 프롬프트 엔지니어링 무료 가이드 정리](/post/2022-12-30-learn-prompting/wordcloud_hu_6a9d105de4834753.webp)
![[CMD] BatchGotAdmin으로 배치 파일 UAC 관리자 권한 자동 요청 가이드](/post/2025-07-17-windows-batch-admin-privilege-uac-elevation-guide/index_hu_5a27e05742e84409.webp)
![[How-To] Windows 10 다중 사용자 카카오톡 실행 권한 부여](/post/2021-04-07-window10-multiuser-kakaotalk/wordcloud_hu_5fcf6a8683d09a52.webp)