Jekyll Formspree

A Jekyll plugin that adds a {% formspree %} Liquid tag to render a Formspree contact form.

Requires Jekyll 3.8 to 4.x and Ruby 3.1 or later.

Add the gem to your Gemfile:

group :jekyll_plugins do
  gem "jekyll-formspree"
end

then run bundle install. If you list plugins in _config.yml, add it there too:

plugins:
  - jekyll-formspree

GitHub Pages' built-in Jekyll build only runs allow-listed plugins. To use this plugin there, build the site with a GitHub Actions workflow.

Use your form ID, as shown on Formspree (https://formspree.io/f/<form ID>):

{% formspree "xyzabcde" %}

or read it from a variable, for example from _config.yml (formspree_id: xyzabcde) or from the page's front matter:

{% formspree site.formspree_id %}
{% formspree page.form_id %}

If the ID is empty, the build prints a warning.

Without a custom template, the tag renders:

<form class="formspree-form" action="https://formspree.io/f/xyzabcde" method="POST" accept-charset="utf-8">
  <label for="formspree-email">Your email</label>
  <input type="email" id="formspree-email" name="email" autocomplete="email" required>
  <label for="formspree-message">Your message</label>
  <textarea id="formspree-message" name="message" rows="5" required></textarea>
  <button type="submit">Send</button>
</form>

preceded by a few lines of CSS scoped to .formspree-form.

Create _includes/formspree.html in your site (or in your theme). The tag renders it in the page's context, so page, site and {% include %} work as usual, with two extra variables:

<form action="{{ formspree_url }}" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="hidden" name="_subject" value="Message from {{ page.title }}">
  <button type="submit">Send</button>
</form>

The endpoint prefix defaults to https://formspree.io/f/. To change it:

formspree:
  endpoint: https://formspree.io/f/

• The default form now posts to https://formspree.io/f/<id> instead of https://formspree.io/<id>. Use the form ID shown in your Formspree dashboard.
• Custom templates keep working unchanged. To use the new endpoint, replace https://formspree.io/{{ formspree_id }} with {{ formspree_url }}.

bundle install
bundle exec rake test
JEKYLL_VERSION="~> 3.10" bundle update jekyll && bundle exec rake test

MIT, see LICENSE.