# Jekyll

> A Jekyll include that renders an Ikiform form from _config.yml, with redirects that work on GitHub Pages and custom domains.

Jekyll sites are static, which suits a plain form post. Keep the form in an include so every page uses the same markup and the form id lives in one place.

## Set it up

### Step 1: Add the settings to _config.yml

`_config.yml`:

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

The include builds the redirect with `absolute_url`, which needs `url`. Without it, the redirect is only a path, and Ikiform ignores anything that isn't a full `https:` URL. On a GitHub Pages project site, also set `baseurl: /repo`; `absolute_url` adds it for you.

### Step 2: Create the include

`_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>
```

### Step 3: Use it

`contact.md`:

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

Questions about pricing? Write to us.

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

The include works in pages, posts and layouts. Pass `form_id` to use another form, `thanks` for another redirect, and `button` for the button text.

### Step 4: Add the thank-you page

`thanks.md`:

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

Thanks, we got your message.
```

`_redirect` is followed only when the form has allowed domains that include your site. See [Rules for _redirect](https://ikiform.com/docs/html.md#redirect-rules).

## Allowed domains

GitHub Pages is the usual host for Jekyll, so you'll often need two entries: the `github.io` host and your custom domain.

| Where the form runs | Add to Allowed domains |
| --- | --- |
| `bundle exec jekyll serve` | `localhost`. It matches `http://localhost:4000`: Ikiform compares the host name only, never the port. |
| GitHub Pages | `username.github.io`. Project sites at `username.github.io/repo` use the same host, so one entry covers them all. |
| Custom domain on GitHub Pages | `example.com`, which also covers `www.example.com` |
| Netlify | `your-site.netlify.app`. Deploy previews (`deploy-preview-12--your-site.netlify.app`) and branch deploys (`branch--your-site.netlify.app`) are not subdomains of it, so add the exact preview host while you test one. |

- Never add `github.io` on its own. Every site on that host would match, including other people's.

## Test checklist

1. Run `bundle exec jekyll serve` and view the page source. The `action` should end in your form id.
2. Submit locally. You'll land on Ikiform's thank-you page: `jekyll serve` sets `url` to `http://localhost:4000`, and `http:` redirects aren't followed.
3. Push, wait for the Pages build, and submit from `username.github.io`. Confirm the submission isn't marked spam.
4. Submit on your custom domain and confirm you land on `/thanks/`.

## Troubleshooting

| What you see | Why | Fix |
| --- | --- | --- |
| `Could not locate the included file 'ikiform-form.html'` | The file isn't in `_includes`, or the name differs | Move it to `_includes/ikiform-form.html`. |
| Ikiform's thank-you page instead of `/thanks/` on the live site | `url` is missing from `_config.yml`, or the form has no allowed domains | Set `url` to your `https:` address and add your domain. |
| `404 not_found` after submit | `site.ikiform.form_id` is empty, so the action ends in `/f/` | Check the indentation under `ikiform:` in `_config.yml`. |
| Submissions arrive under the spam filter with `origin_mismatch` | The page that posted isn't on the form's allowed domains | Add the host from the table above. With **Reject** chosen, the same posts get `403 origin_not_allowed` instead. |

## Related

- [Hugo](https://ikiform.com/docs/guides/hugo.md): A partial and a shortcode for content files.
- [Eleventy](https://ikiform.com/docs/guides/eleventy.md): A shortcode for Nunjucks, Liquid and Markdown.
- [HTML forms](https://ikiform.com/docs/html.md): Redirects, reserved fields and the honeypot.
- [Allowed domains](https://ikiform.com/docs/spam.md#allowed-domains): How origins are matched, and what a mismatch does.