MkDocs contact form without a server

The thank-you page

After a successful submission the redirect field sends visitors to the thank-you page. It has to be an absolute http(s) URL. Markdown pages can't read site_url, so write the full URL yourself. Without a redirect, Formlane uses the default redirect from your form settings, or its own hosted thank-you page.

• With the default use_directory_urls: true, docs/thanks.md becomes /thanks/. With use_directory_urls: false it is /thanks.html.
• On a GitHub Pages project site, include the repository name: https://user.github.io/repo-name/thanks/.
• not_in_nav keeps the thank-you page out of the navigation without a build notice, and search: exclude: true keeps it out of Material's search.

Optional: stay on the page

If you'd rather show a message without a page change, send the form with fetch(). With Accept: application/json, Formlane answers {"success": true, "message": "Form submitted successfully", "id": "…"} or {"success": false, "error": "limit_reached", "message": "…"} with a 4xx/5xx status. message is always English, so the script shows its own text per error code.

Add the script to mkdocs.yml:

extra_javascript:
  - javascripts/contact-form.js

// Optional: send forms marked with data-formlane via fetch() and show a message
// instead of a page change. Without JavaScript the form still posts normally.
const FORMLANE_MESSAGES = {
  limit_reached: "This form can't take more messages this month. Please email us directly.",
  rate_limited: "Too many messages in a short time. Please try again in a few minutes.",
};
const FORMLANE_FALLBACK = "Sorry, that didn't work. Please try again later.";

function enhanceContactForm(form) {
  if (form.dataset.enhanced) return;
  form.dataset.enhanced = "true";
  const status = form.querySelector(".contact-form-status");
  const button = form.querySelector('button[type="submit"]');

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    button.disabled = true;
    let text = FORMLANE_FALLBACK;
    try {
      const res = await fetch(form.action, {
        method: "POST",
        headers: { Accept: "application/json" },
        body: new FormData(form),
      });
      const json = await res.json().catch(() => ({}));
      // Spam caught by the honeypot or the content rules also gets success: true.
      if (json.success) {
        form.reset();
        text = "Thanks! We'll get back to you.";
      } else {
        text = FORMLANE_MESSAGES[json.error] || FORMLANE_FALLBACK;
      }
    } catch {
      // network error: keep the fallback text
    }
    status.textContent = text;
    status.hidden = false;
    button.disabled = false;
  });
}

function initContactForms() {
  document.querySelectorAll("form[data-formlane]").forEach(enhanceContactForm);
}

// Material's instant navigation swaps pages without a full reload.
// document$ emits after every page load, so the form is found on each visit.
if (typeof document$ !== "undefined") {
  document$.subscribe(initContactForms);
} else {
  initContactForms();
}

If you use Material's navigation.instant, pages are swapped without a full reload, and a script that only runs once won't see a form you navigate to. Subscribing to Material's document$ fixes that. If the script doesn't run for any reason, the browser still posts the form normally and the visitor lands on your thank-you page.

Spam protection without a captcha

• Honeypot: the hidden botcheck checkbox. If a bot ticks it, Formlane returns a normal success response and stores nothing.
• Rate limit: 10 submissions per 10 minutes per visitor and form.
• Content rules: messages with 4 or more links, link markup or typical spam phrases go to a separate spam tab. Spam doesn't count toward your monthly limit.
• Allowed domains: limit the form to your own domain in its settings.

Limits worth knowing

• Up to 64 KB per submission, 50 fields and 10,000 characters per field.
• Content types: application/x-www-form-urlencoded, multipart/form-data (text fields only) and application/json.
• File uploads are not supported yet. If your form needs attachments, use one of the alternatives below.
• Material for MkDocs announces its end of life for May 5, 2027 and points to Zensical as its successor. The form itself is plain HTML, so it doesn't depend on the theme; we haven't tested the optional script with Zensical yet.

Alternatives, honestly compared

Where the data is stored

Stored in Frankfurt, in a Supabase database in the eu-central-1 region. The app runs on Vercel: our server functions run in Frankfurt (fra1); static files and edge routing are served by Vercel's global network. Notification emails are sent through Resend, a US company. All providers are listed in the privacy policy. Formlane is run by Mindcaptain Services OÜ in Tallinn, Estonia. A data processing agreement is included in the Terms (Art. 28 GDPR, smallwerk.com/dpa), and IP hashes are deleted after 30 days. Add the contact form to your own privacy policy, and delete old submissions in the dashboard when you no longer need them.

Pricing

Free: 250 submissions a month and up to 5 forms. Starter: $8/month for 2,500 submissions. Pro: $19/month for 25,000 submissions. Prices are in USD incl. VAT where applicable (also available in EUR). A read-only REST API and MCP server are included on every plan, including Free.

Related guides

• GitHub Pages contact form
• HTML contact form
• Contact form spam without a captcha
• Docusaurus contact form

FAQ