/turnstile-spin

Hugo

For Hugo static sites. The widget renders on any page that includes the partial; siteverify happens at whatever backend handles your form submissions (a Cloudflare Pages Function, a Worker, an external API, or a form host with a server-side hook).

<script
	src="https://challenges.cloudflare.com/turnstile/v0/api.js"
	async
	defer
></script>

<form action="{{ .Site.Params.turnstileFormEndpoint }}" method="POST">
	<input name="email" type="email" required />
	<div
		class="cf-turnstile"
		data-sitekey="{{ .Site.Params.turnstileSitekey }}"
		data-action="subscribe"
	></div>
	<button type="submit">Subscribe</button>
</form>

Add the params to your site config:

[params]
turnstileSitekey = "YOUR_SITEKEY"
turnstileFormEndpoint = "/api/subscribe"  # path to your existing form handler

Reference the partial from any layout or content file:

{{ partial "turnstile.html" . }}

Backend (where siteverify lives)

Hugo doesn't host server-side code, so the form endpoint must live elsewhere. Two common setups:

Cloudflare Pages Function (functions/api/subscribe.js):

export async function onRequestPost({ request, env }) {
	const form = await request.formData();
	const token = form.get("cf-turnstile-response");

	const expectedHostnames = new Set(
		(env.TURNSTILE_HOSTNAMES ?? "")
			.split(",")
			.map((h) => h.trim())
			.filter(Boolean),
	);
	if (expectedHostnames.size === 0) {
		return new Response("forbidden", { status: 403 });
	}

	const r = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body: new URLSearchParams({
			secret: env.TURNSTILE_SECRET,
			response: token,
			remoteip: request.headers.get("CF-Connecting-IP"),
		}),
	});
	const result = await r.json();
	if (
		r.ok !== true ||
		result.success !== true ||
		result.action !== "subscribe" ||
		!expectedHostnames.has(result.hostname)
	) {
		return new Response("forbidden", { status: 403 });
	}

	// process subscribe
	return new Response("ok");
}

subscribe is the stable action for this surface. Preserve an existing custom migration action and compare the returned action to the same value. Siteverify is mandatory for every widget mode, including pre-clearance. Set TURNSTILE_HOSTNAMES to the deployment-specific frontend hostnames; a production value must not include localhost or 127.0.0.1.

After the user approves a canonical absolute WRANGLER_BIN outside the project, set the secret with (set +x; printf '%s' "$WIDGET_SECRET" | "$WRANGLER_BIN" pages secret put TURNSTILE_SECRET) (or use the dashboard's Pages → your project → Settings → Environment variables → Add secret).

External backend: any Node/Ruby/Python/Go handler can do the same call. See the vanilla-html reference for non-Cloudflare-specific snippets.

Variant: shortcode for content files

If you want to drop the widget into Markdown content (not just layouts), create a shortcode:

{{ partial "turnstile.html" . }}

Use in content:

---
title: Contact
---

Contact us:

{{< turnstile-form >}}

Substitutions