# Hugo

> 사이트 파라미터로 Ikiform 폼을 렌더링하는 Hugo 파셜과 쇼트코드. 레이아웃과 Markdown 콘텐츠 모두에서 사용합니다.

Hugo는 일반 HTML을 빌드하고, Ikiform에는 일반 폼 POST면 충분하므로 추가할 JavaScript가 없습니다. Hugo만의 함정은 Markdown입니다. `markup.goldmark.renderer.unsafe`를 켜지 않으면 Hugo의 렌더러가 콘텐츠 파일의 원시 HTML을 제거하므로, 붙여 넣은 폼이 `<!-- raw HTML omitted -->`로 바뀝니다. 쇼트코드를 쓰면 HTML을 템플릿 안에 둘 수 있습니다.

## 설정하기

### 1단계: 설정에 폼 ID 추가하기

`hugo.toml`:

```toml
baseURL = "https://example.com/"

[params.ikiform]
formId = "frm_xxxxxxxxxxxxxxxx"
thanks = "/thanks/"
```

`baseURL`은 실제 `https:` 주소여야 합니다. 파셜이 이 값으로 `thanks`를 절대 URL로 바꾸며, Ikiform은 `https:` 리디렉션만 따릅니다.

### 2단계: 파셜 만들기

`layouts/_partials/ikiform-form.html`:

```html
{{ $id := .id | default site.Params.ikiform.formId }}
{{ $thanks := .thanks | default site.Params.ikiform.thanks }}
<form class="ikiform" action="https://ikiform.com/f/{{ $id }}" method="post">
  <label>Email <input name="email" type="email" autocomplete="email" required></label>
  <label>Message <textarea name="message" rows="5"></textarea></label>
  {{ with .subject }}<input type="hidden" name="_subject" value="{{ . }}">{{ end }}
  {{ with $thanks }}<input type="hidden" name="_redirect" value="{{ . | absURL }}">{{ end }}
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden>
  <button type="submit">{{ .button | default "Send" }}</button>
</form>
```

비어 있더라도 항상 `dict`와 함께 호출하세요. 모든 키는 선택 사항이며 없으면 사이트 파라미터를 사용합니다.

### 3단계: 쇼트코드로 감싸기

`layouts/_shortcodes/ikiform.html`:

```html
{{ partial "ikiform-form.html" (dict "id" (.Get "id") "subject" (.Get "subject") "button" (.Get "button")) }}
```

Hugo 0.146부터 템플릿이 `layouts/_partials`와 `layouts/_shortcodes`로 옮겨졌습니다. 이전 버전에서는 `layouts/partials`와 `layouts/shortcodes`를 사용하세요.

### 4단계: 사용하기

아무 콘텐츠 파일에서:

`content/contact.md`:

```text
---
title: Contact
---

Questions about pricing? Write to us.

{{< ikiform subject="Pricing question" >}}
```

또는 모든 페이지에 폼을 넣으려면 레이아웃에서:

`layouts/_partials/footer.html`:

```html
<footer>
  {{ partial "ikiform-form.html" (dict "subject" "Footer enquiry") }}
</footer>
```

리디렉션용으로 `content/thanks.md` 페이지를 추가하세요. Ikiform은 폼의 허용 도메인에 여러분의 사이트가 포함된 경우에만 `_redirect`를 따르며, 그렇지 않으면 방문자에게 Ikiform의 감사 페이지가 보입니다. [_redirect 규칙](https://ikiform.com/ko/docs/html.md#redirect-rules)을 참고하세요.

## 허용 도메인

프로덕션 도메인과, 빌드된 사이트를 미리 보는 모든 곳을 등록하세요.

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

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

## 테스트 체크리스트

1. `hugo server`를 실행하고 페이지를 열어 소스를 보세요. `<!-- raw HTML omitted -->`가 아니라 `<form>`이 보여야 합니다.
2. 허용 도메인에 `localhost`를 넣고 로컬에서 제출하세요. `absURL`이 `http://localhost` 주소를 만들고 `https:` 리디렉션만 따르기 때문에 Ikiform의 감사 페이지로 이동합니다.
3. 미리보기를 배포해 그곳에서 제출하고, 제출이 Ikiform에 표시되며 스팸으로 표시되지 않았는지 확인하세요.
4. 프로덕션 도메인에서 제출하고 `/thanks/`로 이동하는지 확인하세요.

## 문제 해결

| 증상 | 원인 | 해결 |
| --- | --- | --- |
| 폼이 있어야 할 곳에 `<!-- raw HTML omitted -->`가 있음 | 폼을 Markdown에 바로 붙여 넣음 | 쇼트코드를 사용하세요. |
| Hugo가 `template for shortcode "ikiform" not found`와 함께 실패함 | 쇼트코드 파일이 사용 중인 Hugo 버전이 읽지 않는 폴더에 있음 | 0.146 이상은 `layouts/_shortcodes`, 그 이전은 `layouts/shortcodes`를 사용하세요. |
| 프로덕션에서 `/thanks/` 대신 Ikiform의 감사 페이지가 나옴 | 허용 도메인이 없거나 `baseURL`이 `http:`임 | 도메인을 추가하고 `baseURL`을 `https:` 주소로 설정하세요. |
| 제출 후 `404 not_found` | `params.ikiform.formId`가 없어서 action이 `/f/`로 끝남 | `hugo.toml`에 폼 ID를 설정하세요. |
| 제출이 `origin_mismatch`와 함께 스팸 필터에 들어감 | POST한 페이지가 폼의 허용 도메인에 없음 | 위 표의 호스트를 추가하세요. **Reject**를 골랐다면 같은 POST가 대신 `403 origin_not_allowed`를 받습니다. |

## 관련 문서

- [Jekyll](https://ikiform.com/ko/docs/guides/jekyll.md): 인클루드와 GitHub Pages 설정.
- [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): 출처를 비교하는 방식과 불일치 시 동작.