데이터 모델

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.

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

사이트 작성자

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.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 기본
• 함수 — 데이터 조회 함수
• 필터 — 값 변환