# Jekyll

> _config.yml의 값으로 Ikiform 폼을 렌더링하는 Jekyll 인클루드. GitHub Pages와 커스텀 도메인에서 작동하는 리디렉션을 함께 설정합니다.

Jekyll 사이트는 정적이라 일반 폼 POST에 잘 맞습니다. 폼을 인클루드에 두면 모든 페이지가 같은 마크업을 쓰고 폼 ID도 한곳에서 관리할 수 있습니다.

## 설정하기

### 1단계: _config.yml에 설정 추가하기

`_config.yml`:

```yaml
url: "https://example.com"
ikiform:
  form_id: frm_xxxxxxxxxxxxxxxx
  thanks: /thanks/
```

인클루드는 `absolute_url`로 리디렉션 주소를 만들며, 여기에는 `url`이 필요합니다. 없으면 리디렉션이 경로만 남는데, Ikiform은 완전한 `https:` URL이 아니면 무시합니다. GitHub Pages 프로젝트 사이트라면 `baseurl: /repo`도 설정하세요. `absolute_url`이 알아서 붙여 줍니다.

### 2단계: 인클루드 만들기

`_includes/ikiform-form.html`:

```liquid
{%- assign form_id = include.form_id | default: site.ikiform.form_id -%}
{%- assign thanks = include.thanks | default: site.ikiform.thanks -%}
<form class="ikiform" action="https://ikiform.com/f/{{ form_id }}" method="post">
  <label>Email <input name="email" type="email" autocomplete="email" required></label>
  <label>Message <textarea name="message" rows="5"></textarea></label>
  {%- if include.subject %}
  <input type="hidden" name="_subject" value="{{ include.subject | escape }}">
  {%- endif %}
  {%- if thanks %}
  <input type="hidden" name="_redirect" value="{{ thanks | absolute_url }}">
  {%- endif %}
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden>
  <button type="submit">{{ include.button | default: "Send" }}</button>
</form>
```

### 3단계: 사용하기

`contact.md`:

```liquid
---
layout: page
title: Contact
---

Questions about pricing? Write to us.

{% include ikiform-form.html subject="Pricing question" %}
```

인클루드는 페이지, 포스트, 레이아웃에서 작동합니다. 다른 폼을 쓰려면 `form_id`를, 다른 리디렉션에는 `thanks`를, 버튼 텍스트에는 `button`을 전달하세요.

### 4단계: 감사 페이지 추가하기

`thanks.md`:

```liquid
---
layout: page
title: Thanks
permalink: /thanks/
---

Thanks, we got your message.
```

`_redirect`는 폼의 허용 도메인에 여러분의 사이트가 포함된 경우에만 따릅니다. [_redirect 규칙](https://ikiform.com/ko/docs/html.md#redirect-rules)을 참고하세요.

## 허용 도메인

Jekyll은 보통 GitHub Pages에 호스팅하므로 `github.io` 호스트와 커스텀 도메인, 두 항목이 필요한 경우가 많습니다.

| 폼이 실행되는 곳 | Allowed domains에 추가할 값 |
| --- | --- |
| `bundle exec jekyll serve` | `localhost`. `http://localhost:4000`과 일치합니다. Ikiform은 포트가 아니라 호스트 이름만 비교합니다. |
| GitHub Pages | `username.github.io`. `username.github.io/repo`의 프로젝트 사이트도 같은 호스트를 쓰므로 하나만 등록하면 모두 포함됩니다. |
| GitHub Pages의 커스텀 도메인 | `example.com`, `www.example.com`도 포함 |
| Netlify | `your-site.netlify.app`. 배포 미리보기(`deploy-preview-12--your-site.netlify.app`)와 브랜치 배포(`branch--your-site.netlify.app`)는 하위 도메인이 아니므로, 테스트하는 동안 정확한 미리보기 호스트를 추가하세요. |

- `github.io`만 단독으로 추가하지 마세요. 다른 사람의 사이트를 포함해 그 호스트의 모든 사이트가 일치하게 됩니다.

## 테스트 체크리스트

1. `bundle exec jekyll serve`를 실행하고 페이지 소스를 보세요. `action`이 여러분의 폼 ID로 끝나야 합니다.
2. 로컬에서 제출하세요. `jekyll serve`가 `url`을 `http://localhost:4000`으로 설정하고 `http:` 리디렉션은 따르지 않으므로 Ikiform의 감사 페이지로 이동합니다.
3. 푸시하고 Pages 빌드를 기다린 뒤 `username.github.io`에서 제출하세요. 제출이 스팸으로 표시되지 않았는지 확인하세요.
4. 커스텀 도메인에서 제출하고 `/thanks/`로 이동하는지 확인하세요.

## 문제 해결

| 증상 | 원인 | 해결 |
| --- | --- | --- |
| `Could not locate the included file 'ikiform-form.html'` | 파일이 `_includes`에 없거나 이름이 다름 | `_includes/ikiform-form.html`로 옮기세요. |
| 실제 사이트에서 `/thanks/` 대신 Ikiform의 감사 페이지가 나옴 | `_config.yml`에 `url`이 없거나, 폼에 허용 도메인이 없음 | `url`을 `https:` 주소로 설정하고 도메인을 추가하세요. |
| 제출 후 `404 not_found` | `site.ikiform.form_id`가 비어 있어서 action이 `/f/`로 끝남 | `_config.yml`에서 `ikiform:` 아래의 들여쓰기를 확인하세요. |
| 제출이 `origin_mismatch`와 함께 스팸 필터에 들어감 | POST한 페이지가 폼의 허용 도메인에 없음 | 위 표의 호스트를 추가하세요. **Reject**를 골랐다면 같은 POST가 대신 `403 origin_not_allowed`를 받습니다. |

## 관련 문서

- [Hugo](https://ikiform.com/ko/docs/guides/hugo.md): 파셜과 콘텐츠 파일용 쇼트코드.
- [Eleventy](https://ikiform.com/ko/docs/guides/eleventy.md): Nunjucks, Liquid, Markdown용 쇼트코드.
- [HTML 폼](https://ikiform.com/ko/docs/html.md): 리디렉션, 예약 필드, 허니팟.
- [허용 도메인](https://ikiform.com/ko/docs/spam.md#allowed-domains): 출처를 비교하는 방식과 불일치 시 동작.