자동 OG 이미지
Hwaro는 프론트 매터에 커스텀 image가 없는 모든 페이지에 1200x630 Open Graph 미리보기 이미지를 자동 생성합니다. 생성된 경로가 page.image로 설정되어 og:image 메타 태그가 자동으로 이를 사용하므로, 템플릿을 고칠 필요가 없습니다.
이 페이지의 자동 생성 OG 이미지 (style = "terminal").
빠른 시작
[og.auto_image]
enabled = true
style = "terminal"
accent_color = "#2ee66b"
logo = "static/logo.png"
설정
| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| enabled | bool | false |
자동 OG 이미지 생성 여부 |
| style | string | "default" |
구성 프리셋 — 스타일 프리셋 참고 |
| background | string | "#171310" |
배경색(hex) |
| text_color | string | "#f4ede4" |
제목과 설명의 텍스트 색 |
| accent_color | string | "#ec7a66" |
룰, 브랜드 마크, 색 블록에 쓰는 액센트 색 |
| secondary_color | string | — | 투톤 스타일(split, brutalist, bauhaus, …)의 두 번째 색. 생략하면 accent_color에서 자동 파생 |
| font_size | int | 48 |
제목 폰트 크기(px). 더 큰 값을 지정하지 않으면 각 스타일이 자체 스케일로 자동 확대 |
| logo | string | — | 이미지에 삽입할 로고 파일 경로 (예: static/logo.png) |
| logo_position | string | "bottom-left" |
bottom-left, bottom-right, top-left, top-right |
| show_title | bool | true |
사이트 이름 표시 (하단 브랜드 행, 또는 스타일별 자리 — 아이브로, 키커, 창 제목 표시줄) |
| output_dir | string | "og-images" |
생성 이미지를 담을 디렉터리 |
| format | string | "png" |
"png" 또는 "svg". 소셜 플랫폼은 SVG og:image를 렌더링하지 않으므로 PNG가 기본값 |
| font_path | string | — | PNG 출력용 커스텀 .ttf/.otf. 폰트 체인의 맨 앞에 오고, 없는 글리프는 번들 폰트로 대체 |
| background_image | string | — | 텍스트 뒤에 합성할 배경 사진 |
| overlay_opacity | float | 0.45 |
background 색이 사진을 덮는 정도 (0.0 = 사진 그대로, 1.0 = 사진 가림) |
| text_panel | float | 0.0 |
0.0–0.6. 복잡한 배경에서 가독성을 높이는 텍스트 뒤 소프트 패널 |
| pattern_opacity | float | 0.35 |
패턴 스타일(dots, grid, …)의 최대 알파. 각 패턴은 이 값을 정점으로 내부에서 점차 옅어짐 |
| pattern_scale | float | 1.0 |
패턴 스타일의 배율 (최소 0.1) |
| accent_bars | bool | false |
패턴 스타일에 클래식한 얇은 상/하단 액센트 바 추가 |
| lazy_generate | bool | false |
hwaro serve에서 일괄 생성을 건너뛰고 첫 요청 때 렌더링. 대규모 사이트에 권장. hwaro build에는 영향 없음 |
제목은 Space Grotesk, 설명은 Space Grotesk Medium, terminal 스타일은 JetBrains Mono로 렌더링됩니다. 모두 바이너리에 번들되어 있어 PNG 출력이 어떤 머신에서든 동일합니다. 제목에 필요하면 CJK를 지원하는 시스템 폰트가 체인에 자동으로 추가되고, 그 밖의 모든 경우는 DejaVu Sans Bold가 받쳐 줍니다.
스타일 프리셋
style 옵션이 구성 전체를 결정합니다. 아래 미리보기를 클릭하면 확대됩니다.
Signature — 그 자체로 완결된 구성:
| 스타일 | 설명 |
|---|---|
terminal |
신호등 버튼, $ 프롬프트, 블록 커서가 있는 코드 에디터 창. 개발 블로그와 문서용 |
bauhaus |
액센트/보조/파생 색으로 구성한 평면 기하학 아트 포스터 도형 |
halftone |
오른쪽 가장자리에서 번져 들어오는 인쇄풍 하프톤 도트 필드 |
Modern — 생성된 배경 위의 타이포그래피 중심 구성:
| 스타일 | 설명 |
|---|---|
editorial |
잡지 표지풍: 헤어라인 룰, 대문자 사이트명 키커, 세로 액센트 룰. 무난하고 조화로운 기본 선택지 |
artistic |
필름 그레인을 더한 메시 그라디언트 색 필드. 완성도 높은 풍부한 느낌 |
hero |
스포트라이트 글로우, 제목 첫 단어의 거대한 고스트 에코, 포스터 타이포그래피 |
surreal |
오로라 구체와 흐르는 리본 밴드에 그레인을 더한 구성 |
monument |
극단적 미니멀리즘 — 거대한 타이포, 넓은 여백, 제목 위 액센트 룰, 오른쪽 아래 브랜드 행 |
framed |
초대장 카드: 중립 색 헤어라인 프레임에 액센트 코너 브래킷과 가운데 정렬 타이포 |
Geometric — 대담한 평면 색 블로킹:
| 스타일 | 설명 |
|---|---|
split |
왼쪽 대각선 투톤 색 블록, 오른쪽 제목 |
band |
제목을 뚫어낸 전체 폭 색 밴드와 그 위를 받치는 얇은 룰 — 잡지 표지 스타일 |
brutalist |
강한 오프셋 그림자와 거대한 타이포가 있는 두꺼운 프레임 패널 |
Patterns — 초점이 있는 구성 (각 패턴은 pattern_opacity를 정점으로 내부에서 점차 옅어짐):
| 스타일 | 설명 |
|---|---|
default |
머스트헤드: 상단의 대문자 사이트명 아이브로, 낮은 코너 글로우, 은은한 비네트 |
minimal |
타이포만 — 제목 뒤의 액센트 마침표가 전부 |
dots |
오른쪽 위 모서리에서 번져 들어오는 엇갈린 하프톤 도트 |
grid |
초점 크로스헤어와 레지스트레이션 마크가 있는 가는 청사진 그리드 |
diagonal |
오른쪽 아래 모서리의 45° 스트라이프 쐐기와 빗변의 액센트 룰 |
gradient |
코너 글로우, 비네트, 그레인이 있는 액센트 톤 듀오톤 워시 |
waves |
아래 가장자리에 겹겹이 쌓인 물결 밴드 |
미리보기
terminal
bauhaus
halftone
editorial
artistic
hero
surreal
monument
framed
split
band
brutalist
default
minimal
dots
grid
diagonal
gradient
waves
배경 이미지
사진을 텍스트 뒤에 합성합니다:
[og.auto_image]
enabled = true
style = "editorial"
background_image = "static/og-bg.jpg"
overlay_opacity = 0.55
렌더링 순서는 배경색 → 사진 → 색 오버레이 → 스타일 구성 → 텍스트/로고입니다. overlay_opacity는 배경색이 사진을 얼마나 덮을지 결정합니다. 자체 배경을 생성하는 스타일(artistic, hero, surreal)은 사진이 설정되면 배경 생성을 건너뛰어 사진이 그대로 드러납니다.
미리보기
아래 예시는 overlay_opacity만 다릅니다 (같은 사진, style = "editorial", 검정에 가까운 background). 클릭하면 확대됩니다.
overlay_opacity = 0.3
overlay_opacity = 0.55
overlay_opacity = 0.8
출력 포맷
PNG가 기본값입니다. stb_truetype과 stb_image_write로 자체 렌더링하므로 외부 도구가 필요 없습니다. 폰트는 바이너리에 번들되어 있으며(Space Grotesk, JetBrains Mono, 넓은 문자 범위를 받쳐 주는 DejaVu Sans Bold), 시스템 폰트는 CJK 텍스트에만 사용합니다.
시스템에 CJK 폰트가 있으면 CJK 제목과 설명에 별도 설정이 필요 없습니다. Hwaro가 처음 찾은 폰트(macOS는 Arial Unicode, Apple SD Gothic Neo, PingFang, Hiragino Sans GB, Linux는 Noto Sans CJK)를 폰트 체인에 추가합니다. 최소 구성의 Linux 컨테이너나 CI 러너처럼 CJK 폰트가 없는 환경에서는 CJK 문자가 이미지에서 빠지므로, Noto Sans CJK를 설치하거나 font_path에 CJK를 지원하는 폰트를 지정하세요. font_path를 설정하면 이 시스템 폰트 탐색을 대신하므로, 지정한 폰트가 CJK 글리프를 직접 포함해야 합니다.
의존성 없는 SVG 출력이 필요하면 format = "svg"로 설정합니다. 다만 소셜 플랫폼은 일반적으로 SVG og:image를 렌더링하지 않습니다.
증분 생성
Hwaro는 생성 이미지 옆에 .og_manifest.json을 저장하고 입력이 바뀌지 않은 페이지를 건너뜁니다. 빌드 간에 출력 디렉터리를 유지하면(예: --cache 모드) 증분 생성이 자동으로 동작합니다. hahwul/hwaro GitHub Action은 이를 알아서 처리합니다.
| 변경 | 재생성 대상 |
|---|---|
| 페이지 제목, 설명, URL | 해당 페이지만 |
| OG 설정, 또는 로고/배경 이미지의 파일 내용 | 전체 페이지 |
| 디스크에 이미지 파일이 없음 | 해당 페이지만 |
개발 서버 속도 개선
OG 생성은 대규모 사이트에서 가장 비용이 큰 빌드 단계 중 하나입니다. 두 가지 방법이 있습니다:
lazy_generate = true—hwaro serve가 일괄 생성을 건너뛰고, 각 이미지는 해당 페이지의 첫 요청 때 렌더링된 뒤 캐시됩니다.hwaro build에는 영향이 없습니다.hwaro serve --fast-start와 잘 어울립니다.hwaro build --skip-og-image— OG 이미지를 아예 건너뜁니다.
동작
- 프론트 매터에 커스텀
image가 있는 페이지는 그대로 유지하고, 초안은 건너뜁니다 - 긴 제목은 자동으로 줄바꿈됩니다 (CJK 인식)
- 로고와 배경 이미지는 한 번만 로드해 전체 페이지에서 재사용합니다
출력
/posts/hello-world/ 페이지는 public/og-images/posts-hello-world.png와 다음 태그를 만듭니다:
<meta property="og:image" content="https://example.com/og-images/posts-hello-world.png">
특정 페이지에 커스텀 이미지를 쓰려면 프론트 매터에 image를 설정합니다:
+++
title = "My Post"
image = "/images/custom-og.png"
+++