데이터 모델

Hwaro의 템플릿 시스템은 Site, Section, Page 세 가지 핵심 타입을 중심으로 동작합니다. 이 페이지는 템플릿 쪽 레퍼런스로, 템플릿을 만들 때 쓸 수 있는 모든 속성과 변수를 다룹니다. 콘텐츠 작성과 프론트 매터 필드 설정은 콘텐츠 작성을 참고합니다.

계층 구조

Site
├── Config (title, base_url, ...)
├── Pages[] (standalone pages)
├── Sections[]
│   ├── Pages[] (pages in section)
│   └── Subsections[]
│       ├── Pages[]
│       └── Subsections[] (recursive)
└── Taxonomies{}
    └── Terms{}
        └── Pages[]

관계

• Site는 여러 Section과 독립 Page를 포함합니다
• Section은 Page와 자식 Subsection을 포함합니다
• Subsection은 제한 없이 중첩됩니다
• Taxonomy는 항목별로 Page를 묶습니다

Site

최상위 컨테이너입니다. config.toml에서 설정합니다.

속성

플랫 별칭

데이터 디렉터리

보조 데이터는 data/ 디렉터리에 둡니다. .yml, .yaml, .json, .toml로 끝나는 파일은 자동으로 로드되어 site.data로 노출됩니다.

파일 구조

data/
├── authors.yml
├── products.json
├── config.toml
└── users/
    ├── alice.yml
    ├── bob.yml
    └── cho.yml

데이터 접근

데이터는 확장자를 뺀 파일 이름으로 접근합니다.

예를 들어 data/products.json이 다음과 같다면:

[
  {"name": "Widget", "price": 10},
  {"name": "Gadget", "price": 20}
]

템플릿에서 이렇게 접근합니다.

{% for product in site.data.products %}
  <h2>{{ product.name }}</h2>
  <p>{{ product.price }}</p>
{% endfor %}

하위 디렉터리

data/ 아래의 하위 디렉터리는 중첩된 맵이 됩니다. 각 파일은 확장자를 뺀 파일 이름을 키로 하는 자식이 되고, 부모 디렉터리 자체는 순회할 수 있습니다.

위 구조에서 data/users/alice.yml, data/users/bob.yml, data/users/cho.yml은 다음과 같이 노출됩니다.

• site.data.users.alice, site.data.users.bob, site.data.users.cho — 개별 파일 내용
• site.data.users — 모든 사용자를 순회할 수 있는 맵

{% for name, user in site.data.users %}
  <h3>{{ name }}</h3>
  <p>{{ user.bio }}</p>
{% endfor %}

디렉터리는 얼마든지 중첩됩니다: data/users/admins/root.yml → site.data.users.admins.root.

타임아웃. 소스마다 연결 10초, 읽기 1회당 30초, 그리고 전체 120초가 주어집니다. 마지막 제한은 모든 리디렉션 구간과 본문 전체를 아우르므로, 읽기 타임아웃을 아슬아슬하게 피하며 바이트를 흘려보내는 소스가 빌드를 붙잡아 둘 수 없습니다. 어느 하나라도 초과하면 다른 실패와 마찬가지로 on_error가 처리합니다.

충돌. 디렉터리와 파일이 같은 이름을 공유하면(예: data/users.yml과 data/users/가 나란히 있는 경우) 디렉터리가 우선하고 파일은 무시됩니다. 가려진 파일이 조용히 사라지지 않도록 Hwaro는 빌드 중에 경고를 출력합니다.

원격 데이터 소스

site.data는 config.toml에 선언한 HTTP(S) 엔드포인트에서도 채울 수 있습니다. 각 소스는 빌드당 한 번, 렌더링이 시작되기 전에 가져옵니다. 템플릿은 네트워크 요청을 일으키지 않고, 빌드가 접근하는 모든 엔드포인트를 한곳에서 볼 수 있습니다.

캐시 동작, 오프라인 오류 정책, 타임아웃, 보안 범위를 포함한 독립 설정 안내는 원격 데이터 소스를 참고하세요.

[[data.remote]]
key = "team"                # site.data.team으로 노출
url = "https://api.example.com/team"
format = "json"             # json | toml | yaml | csv (생략 가능, 아래 추론 참고)
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # 캐시된 사본이 이 시간보다 젊으면 요청을 건너뜀
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip

템플릿에서는 로컬 데이터 파일과 똑같이 site.data.team으로 사용합니다. 따라서 어떤 키를 data/team.json과 원격 소스 사이에서 옮겨도 템플릿은 손댈 필요가 없습니다. 레코드를 템플릿에 공급하는 대신 페이지 자체로 만들려면 콘텐츠 생성을 참고하세요.

CSV 페이로드는 행의 배열로 파싱되며 각 행은 공백을 제거한 문자열 셀의 배열입니다. load_data()가 .csv 파일에 대해 만드는 것과 같은 모양입니다.

환경 변수. url과 headers 값의 ${VAR}는 환경 변수로 치환됩니다. 참조한 변수가 설정되어 있지 않으면 변수 이름을 명시한 오류와 함께 빌드가 실패합니다(config.toml의 다른 곳에서는 경고에 그칩니다). 기본값이 필요하면 ${VAR:-default}를 쓰세요. 이 오류는 소스를 실제로 가져오는 시점에 발생하므로, 네트워크를 쓰지 않는 hwaro deploy, hwaro new, hwaro tool ...은 변수를 내보내지 않아도 그대로 동작합니다.

캐싱. 페이로드는 .hwaro/remote_data/ 아래에 캐시됩니다. data/를 비롯해 hwaro serve가 감시하는 어떤 디렉터리에도 속하지 않으므로, TTL 안의 serve 재빌드는 API를 다시 호출하는 대신 캐시를 재사용하고, 캐시 기록이 재빌드를 유발하지도 않습니다. 이 캐시는 hwaro build --full에도 지워지지 않으며(페이지 캐시만 초기화됩니다), on_error = "warn-and-use-cache"와 함께 오프라인 빌드를 가능하게 하는 것도 이 캐시입니다. .hwaro/는 생성 시 자기 자신을 무시하는 .hwaro/.gitignore가 함께 쓰이므로 캐시가 git status에 나타나지 않습니다. 긴 hwaro serve 세션에서는 각 소스를 한 번 가져와 메모리에서 재사용합니다. cache TTL이 있는 항목은 TTL이 만료된 뒤 첫 전체 재빌드에서 다시 가져오고, TTL이 없는 항목은 저장할 때마다가 아니라 세션당 한 번만 가져옵니다. 세션이 이미 페이로드를 갖고 있는 상태에서 재요청이 실패하면 on_error 설정과 무관하게 경고를 남기고 기존 페이로드를 계속 사용하므로, 오프라인에서도 편집을 이어갈 수 있습니다. hwaro build는 빌드마다 별도 프로세스이므로 영향이 없으며 cache/on_error를 그대로 따릅니다. 페이로드가 바뀌면 data/ 파일을 편집했을 때와 같은 방식으로 캐시된 페이지가 무효화됩니다.

충돌. 원격 key가 디스크에도 존재하면(예: key = "team" 옆에 data/team.json) 두 소스를 모두 명시한 설정 오류가 발생합니다. 하나의 키는 정확히 하나의 소스만 가져야 하므로, site.data.team이 어느 쪽이 이기는지에 따라 조용히 달라지는 일은 없습니다.

원격 소스는 의도적으로 설정 전용입니다. load_data()와 숏코드는 URL을 받을 수 없습니다. 소스마다 GET 요청 하나 이상이 필요하다면(페이지네이션, POST 본문, 응답 가공) 사전 빌드 훅으로 data/에 받아 두세요.

사이트 작성자

Hwaro는 프론트 매터의 authors 필드(authors = ["id"])에 정의된 모든 작성자를 site.authors로 자동 집계합니다.

작성자 정의

data/authors.yml(또는 .json, .toml) 파일을 만들어 작성자 데이터를 보강할 수 있습니다. 키는 페이지 프론트 매터에서 쓴 작성자 ID와 일치해야 합니다.

content/my-post.md

---
title: "My Post"
authors: ["john-doe"]
---

data/authors.yml

john-doe:
  name: "John Doe"
  bio: "Creator of things."
  avatar: "/images/john.jpg"

템플릿에서 사용

site.authors 객체는 사이트에서 발견된 모든 작성자를 담습니다. 각 작성자 객체는 다음을 갖습니다.

• key: 작성자 ID(예: "john-doe")
• name: 작성자 이름(데이터에서 가져오거나, 없으면 ID로 폴백)
• pages: 이 작성자가 쓴 페이지 목록(날짜순 정렬)
• data/authors.yml에 정의한 모든 커스텀 필드

{% for id, author in site.authors %}
  <div class="author">
    <img src="{{ author.avatar }}" alt="{{ author.name }}">
    <h3>{{ author.name }}</h3>
    <p>{{ author.bio }}</p>

    <h4>Recent Posts</h4>
    <ul>
    {% for p in author.pages %}
      <li><a href="{{ p.url }}">{{ p.title }}</a></li>
    {% endfor %}
    </ul>
  </div>
{% endfor %}

예시

<title>{{ site.title }}</title>
<link rel="canonical" href="{{ site.base_url }}{{ page.url }}">

Section

관련 콘텐츠를 묶는, _index.md가 있는 디렉터리입니다.

속성

section.html에서 현재 섹션의 URL이 필요하면 page.url을 사용합니다.

플랫 별칭

프론트 매터에서 오는 속성

페이지 순회

{% for p in section.pages %}
<article>
  <h2><a href="{{ p.url }}">{{ p.title }}</a></h2>
  <time>{{ p.date }}</time>
  {% if p.description %}
  <p>{{ p.description }}</p>
  {% endif %}
</article>
{% endfor %}

하위 섹션 순회

{% for sub in section.subsections %}
<div class="category">
  <a href="{{ sub.url }}">{{ sub.title }}</a>
  <span>({{ sub.pages_count }} articles)</span>
</div>
{% endfor %}

section_list 사용

단순한 목록에는 미리 렌더링된 HTML을 사용합니다.

<ul>{{ section_list | safe }}</ul>

마크업을 직접 구성하려면 section.pages를 순회합니다.

<ul>
{% for p in section.pages %}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    {% if p.date %}<time>{{ p.date }}</time>{% endif %}
  </li>
{% endfor %}
</ul>

Page

개별 콘텐츠 파일(.md)입니다.

핵심 속성

렌더링된 HTML 콘텐츠는 최상위 content 변수로 제공됩니다.

메타데이터 속성

계산 속성

불리언 플래그

내비게이션 속성

커스텀 메타데이터

플랫 별칭

내비게이션 객체

page.lower / page.higher

내비게이션은 mdBook이나 Docusaurus처럼 사이트 전체를 하나로 펼친 읽기 순서를 따릅니다. 페이지는 섹션 트리를 깊이 우선으로 순회하는 순서로 정렬됩니다: 섹션 인덱스 → 섹션 페이지 → 하위 섹션(재귀). 각 섹션 안에서는 그 섹션의 sort_by 설정(weight, date, title)에 따라 정렬됩니다.

<nav class="post-nav">
  {% if page.lower %}
  <a href="{{ page.lower.url }}">← {{ page.lower.title }}</a>
  {% endif %}
  
  {% if page.higher %}
  <a href="{{ page.higher.url }}">{{ page.higher.title }} →</a>
  {% endif %}
</nav>

page.ancestors

브레드크럼에 쓰는 부모 섹션 목록:

<nav class="breadcrumbs">
  <a href="/">Home</a>
  {% for ancestor in page.ancestors %}
  / <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
  {% endfor %}
  / <span>{{ page.title }}</span>
</nav>

page.version

[[versions.list]]가 있는 사이트에서만 제공됩니다(버전별 문서 참고). 어떤 버전 디렉터리에도 속하지 않는 페이지에서는 nil입니다.

page.version_links

설정된 버전마다 한 행씩, 설정 순서대로.

{% for v in page.version_links %}
<a href="{{ base_url }}{{ v.url }}"{% if v.current %} aria-current="page"{% endif %}>{{ v.label }}</a>
{% endfor %}

전역 versions 리스트({% for v in versions %}, versions.latest, versions.all)는 현재 페이지 언어 기준 모든 버전의 루트 URL을 노출합니다.

page.translations

{% if page.translations %}
<nav class="lang-switcher">
{% for t in page.translations %}
  {% if t.is_current %}
  <span>{{ t.code | upper }}</span>
  {% else %}
  <a href="{{ t.url }}">{{ t.code | upper }}</a>
  {% endif %}
{% endfor %}
</nav>
{% endif %}

page.extra 접근

프론트 매터의 커스텀 메타데이터:

+++
title = "Review"

[extra]
rating = 4.5
featured = true
pros = ["Fast", "Reliable"]
+++

{% if page.extra.featured %}
<span class="badge">Featured</span>
{% endif %}

<div class="rating">{{ page.extra.rating }} / 5</div>

<ul>
{% for pro in page.extra.pros %}
  <li>{{ pro }}</li>
{% endfor %}
</ul>

프론트 매터 최상위에 쓴 outputs = ["json"]도 마찬가지로 알려지지 않은 일반 키로 취급되어 page.extra.outputs에 들어가며, 해당 페이지/섹션에 한해 [outputs] 설정 기본값을 재정의합니다. 출력 포맷을 참고합니다.

시간 변수

<footer>&copy; {{ current_year }} {{ site.title }}</footer>

SEO 변수

미리 렌더링된 HTML(하위 호환):

<head>
  {{ og_all_tags | safe }}
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ pagination_seo_links | safe }}
</head>

메타 태그 마크업을 직접 구성할 때 쓰는 구조화된 데이터:

페이지 제목, 설명, URL, 이미지는 page.title, page.description, page.url, page.image로 얻습니다. seo 객체는 SEO에 특화된 계산 값(해석된 URL, 설정 값)을 제공합니다.

<head>
  <link rel="canonical" href="{{ seo.canonical_url }}">
  <meta property="og:title" content="{{ page.title }}">
  <meta property="og:type" content="{{ seo.og_type }}">
  <meta property="og:url" content="{{ seo.canonical_url }}">
  {% if page.description %}
  <meta property="og:description" content="{{ page.description }}">
  {% endif %}
  {% if seo.og_image %}
  <meta property="og:image" content="{{ seo.og_image }}">
  {% endif %}
  <meta name="twitter:card" content="{{ seo.twitter_card }}">
  {% if seo.twitter_site %}
  <meta name="twitter:site" content="{{ seo.twitter_site }}">
  {% endif %}
</head>

에셋 변수

편의를 위해 미리 렌더링된 <link>·<script> 태그입니다. config.toml 설정에서 생성됩니다.

<head>
  {{ highlight_css | safe }}
  {{ auto_includes_css | safe }}
</head>
<body>
  ...
  {{ highlight_js | safe }}
  {{ auto_includes_js | safe }}
</body>

목차

프론트 매터에 toc = true가 있을 때만 사용할 수 있습니다.

미리 렌더링된 HTML(하위 호환):

{% if page.toc %}
<aside class="toc">
  {{ toc | safe }}
</aside>
{% endif %}

목차 마크업을 직접 구성할 때 쓰는 구조화된 데이터:

{% if page.toc %}
<nav class="toc">
  <ul>
  {% for h in toc_obj.headers %}
    <li>
      <a href="{{ h.permalink }}">{{ h.title }}</a>
      {% if h.children %}
      <ul>
        {% for child in h.children %}
        <li><a href="{{ child.permalink }}">{{ child.title }}</a></li>
        {% endfor %}
      </ul>
      {% endif %}
    </li>
  {% endfor %}
  </ul>
</nav>
{% endif %}

Paginator

섹션·택소노미 항목 템플릿에서 페이지네이션이 활성화된 경우(섹션 프론트 매터의 paginate, 택소노미는 paginate_by) 사용할 수 있습니다. 1페이지는 섹션 URL에, 이후 페이지는 {url}/{paginate_path}/{n}/에 생성됩니다.

같은 데이터를 pagination_obj 변형으로도 쓸 수 있습니다. previous_url, next_url, first_url, last_url, current_page, total_pages, total_items, per_page, has_previous, has_next, 그리고 html(미리 렌더링된 내비게이션, 플랫 변수 pagination으로도 제공)을 노출합니다.

{% if paginator is defined and paginator.number_pagers > 1 %}
<nav>
  {% if paginator.previous %}<a href="{{ paginator.previous }}">Prev</a>{% endif %}
  <span>{{ paginator.current_index }} / {{ paginator.number_pagers }}</span>
  {% if paginator.next %}<a href="{{ paginator.next }}">Next</a>{% endif %}
</nav>
{% endif %}

택소노미 변수

택소노미 템플릿에서 사용할 수 있습니다.

목록을 직접 구성하려면 get_taxonomy()를 사용합니다. 택소노미를 참고합니다.

메뉴

site.menus는 기본 언어의 이름 있는 메뉴(설정의 [[menus.*]] + 프론트 매터의 menus/menu 등록)를 노출합니다. 템플릿 안에서는 site.menus.<name>보다 get_menu(name="...")을 권장합니다. 현재 페이지의 언어를 기준으로 해석하고, 없으면 기본 언어로 폴백합니다.

{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}

엔트리 속성

전체 설정/프론트 매터 레퍼런스, 계층 구조, 언어별 동작은 메뉴를 참고합니다.

타입 레퍼런스

요약표

템플릿에서 확인

{# Check for nil #}
{% if page.description %}...{% endif %}

{# Check for empty array #}
{% if page.authors %}...{% endif %}

{# Check for empty string #}
{% if page.description is present %}...{% endif %}

{# Default value #}
{{ page.description | default(value=site.description) }}

함께 보기

• 문법 — Jinja2 기본
• 함수 — 데이터 조회 함수
• 필터 — 값 변환