SEO toolkit for Wagtail CMS - meta tags, Open Graph, Twitter Cards, and Schema.org structured data

These details have not been verified by PyPI

Project description

wagtail-herald

Philosophy

SEO optimization shouldn't require deep technical knowledge. While Wagtail provides excellent content management, setting up proper meta tags, Open Graph, Twitter Cards, and Schema.org structured data requires significant manual work.

wagtail-herald provides a comprehensive SEO solution with just two template tags. Site-wide settings are managed through Wagtail's admin interface, while page-specific SEO can be configured per-page with sensible defaults.

The goal is to help content editors achieve best-practice SEO without touching code, while giving developers full control when needed.

Key Features

Simple Integration - Just 3 template tags: {% seo_head %}, {% seo_body %}, {% seo_schema %}
Site-wide Settings - Configure Organization, favicons, social profiles from admin
Page-level SEO - Uses Wagtail's built-in SEO fields + OG image override
13+ Schema Types - Article, Product, FAQ, Event, LocalBusiness, and more
Automatic BreadcrumbList - Generated from page hierarchy
Locale Support - Per-page language/region targeting with {% page_lang %} tag
Google Tag Manager - GTM integration with noscript fallback
robots.txt Management - Configure robots.txt from admin interface
ads.txt Management - Configure ads.txt (Authorized Digital Sellers) from admin interface
security.txt Management - Configure security.txt (RFC 9116) from admin interface
Custom Code Injection - Add custom HTML to head and body from admin
Japanese UI - Full Japanese localization for admin interface

Installation

pip install wagtail-herald

Add to your INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    # ...
    'wagtail.contrib.settings',  # Required
    'wagtail_herald',
    # ...
]

Quick Start

1. Add Template Tags

{% load wagtail_herald %}
<!DOCTYPE html>
<html lang="{% page_lang %}">
<head>
    {% seo_head %}
</head>
<body>
    {% seo_body %}

    <!-- Your content -->

    {% seo_schema %}
</body>
</html>

That's it! The template tags handle everything:

{% seo_head %} - Meta tags, OG, Twitter Card, favicon, GTM script, custom head HTML
{% seo_body %} - GTM noscript fallback, custom body end HTML
{% seo_schema %} - All JSON-LD structured data
{% page_lang %} - Language code for html lang attribute

2. Configure Site Settings

Go to Settings > SEO Settings in Wagtail admin to configure:

Organization name, logo, type
Social media profiles (Twitter, Facebook)
Default OG image and locale
Favicon and Apple Touch Icon
Google Tag Manager (GTM)
robots.txt content
Custom head/body HTML injection

3. Add SEO Mixin to Pages (Optional)

For page-level SEO control, add the mixin to your page models:

from wagtail.models import Page
from wagtail_herald.models import SEOPageMixin

class ArticlePage(SEOPageMixin, Page):
    # Your fields...

    content_panels = Page.content_panels + [
        # Your panels...
    ]

    promote_panels = Page.promote_panels + SEOPageMixin.seo_panels

This adds an "SEO" panel in the page editor with:

OG image override
Schema type selector (Article, Product, FAQ, etc.)
Locale selector (ja_JP, en_US, en_GB, etc.)
noindex/nofollow options
Canonical URL override

Note: For SEO title and meta description, use Wagtail's built-in seo_title and search_description fields in the Promote tab. The template tags automatically use these fields.

4. Override SEO per Sub-route (RoutablePageMixin)

When using RoutablePageMixin, individual sub-routes often represent different content items that need their own SEO metadata. Pass well-known keys through context_overrides and {% seo_head %} will use them instead of the page object's fields.

Supported context keys:

Key	Overrides
`seo_title`	Page title and OG/Twitter title
`seo_description`	Meta description and OG/Twitter description
`seo_canonical_url`	Canonical URL and `og:url`
`seo_og_image`	OG image and Twitter image (Wagtail Image instance)

from wagtail.contrib.routable_page.models import RoutablePageMixin, path
from wagtail.models import Page

class BlogIndexPage(RoutablePageMixin, Page):

    @path("<slug:slug>/")
    def detail(self, request, slug):
        item = get_object_or_404(BlogPost, slug=slug)
        return self.render(request, context_overrides={
            "seo_title": item.name,
            "seo_description": item.summary,
            "seo_canonical_url": request.build_absolute_uri(),
        })

Any key not provided falls back to the page object's own fields, so you only need to specify what differs per sub-route.

Supported Schema Types

Site-wide (Automatic)

WebSite - Site search box support
Organization - Company/organization info

Page-selectable

Type	Use Case
WebPage	General pages (default)
Article	General articles
NewsArticle	News content
BlogPosting	Blog posts
Product	Product pages
LocalBusiness	Store/business info
Service	Service descriptions
FAQPage	FAQ pages
HowTo	How-to guides
Event	Events
Person	Profile pages
Recipe	Recipes
Course	Online courses
JobPosting	Job listings

Automatic

BreadcrumbList - Generated from page hierarchy

Output Example

`{% seo_head %}` Output

<!-- Basic Meta -->
<title>Page Title</title>
<meta name="description" content="Page description...">
<meta name="robots" content="index, follow">

<!-- Canonical -->
<link rel="canonical" href="https://example.com/page/">

<!-- hreflang (multilingual) -->
<link rel="alternate" hreflang="ja" href="https://example.com/ja/page/">
<link rel="alternate" hreflang="en" href="https://example.com/en/page/">
<link rel="alternate" hreflang="x-default" href="https://example.com/ja/page/">

<!-- Favicon -->
<link rel="icon" type="image/svg+xml" href="/media/favicon.svg">
<link rel="icon" type="image/png" sizes="48x48" href="/media/favicon.png">
<link rel="apple-touch-icon" sizes="180x180" href="/media/apple-touch-icon.png">

<!-- Open Graph -->
<meta property="og:type" content="article">
<meta property="og:title" content="Page Title">
<meta property="og:description" content="Page description...">
<meta property="og:image" content="https://example.com/media/og-image.jpg">
<meta property="og:url" content="https://example.com/page/">
<meta property="og:site_name" content="Site Name">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@handle">
<meta name="twitter:title" content="Page Title">
<meta name="twitter:description" content="Page description...">
<meta name="twitter:image" content="https://example.com/media/og-image.jpg">

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXXXXX');</script>

<!-- Custom Head HTML -->
<script src="https://example.com/custom.js"></script>

`{% seo_body %}` Output

<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>

<!-- Custom Body End HTML -->
<script src="https://widget.example.com/chat.js"></script>

`{% seo_schema %}` Output

<script type="application/ld+json">
[
  {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "name": "Site Name",
    "url": "https://example.com/"
  },
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Company Name",
    "url": "https://example.com/",
    "logo": "https://example.com/media/logo.png",
    "sameAs": [
      "https://twitter.com/company",
      "https://www.facebook.com/company"
    ]
  },
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/"},
      {"@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog/"},
      {"@type": "ListItem", "position": 3, "name": "Article Title"}
    ]
  },
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Article Title",
    "image": ["https://example.com/media/article-image.jpg"],
    "author": {"@type": "Person", "name": "Author Name"},
    "datePublished": "2025-01-15T10:00:00+09:00",
    "dateModified": "2025-01-16T15:30:00+09:00"
  }
]
</script>

Configuration

All settings are optional and configured through Wagtail admin:

Site Settings (Admin UI)

Setting	Description
Organization name	Company/site name for Schema
Organization type	Corporation, LocalBusiness, Person, etc. (use Person for individual/personal sites)
Organization logo	Logo image for Schema
Twitter handle	@username (without @)
Facebook URL	Facebook page URL
Default locale	Default og:locale (e.g., en_US, ja_JP)
Default OG image	Fallback image for social sharing (1200x630)
Favicon (SVG)	SVG favicon for modern browsers (recommended)
Favicon (PNG)	PNG fallback, minimum 48x48 (Google requirement)
Apple Touch Icon	iOS home screen icon (180x180)
GTM Container ID	Google Tag Manager (GTM-XXXXXX)
robots.txt content	Custom robots.txt content
ads.txt content	Authorized Digital Sellers declaration (returns 404 if empty)
security.txt content	Security vulnerability reporting info per RFC 9116 (returns 404 if empty)
Custom head HTML	Custom HTML for `<head>` section
Custom body end HTML	Custom HTML before `</body>` (chat widgets, etc.)

Django Settings (Optional)

# settings.py
WAGTAIL_HERALD = {
    # Default robots meta (can be overridden per-page)
    'DEFAULT_ROBOTS': 'index, follow',

    # OG image rendition filter (1200x630 is optimal for social sharing)
    'OG_IMAGE_FILTER': 'fill-1200x630',

    # Favicon rendition filter (48x48 minimum recommended by Google)
    'FAVICON_FILTER': 'fill-48x48',
}

Locale Support

wagtail-herald provides per-page language and region targeting for mixed-language content.

Use Case: Mixed Language Content

Write Japanese and English articles on the same site by selecting locale per page:

{% load wagtail_herald %}
<!DOCTYPE html>
<html lang="{% page_lang %}">
<head>
    {% seo_head %}
    <!-- Outputs: <meta property="og:locale" content="ja_JP"> -->
</head>

{% page_lang %} - Returns language code (e.g., ja, en)
{% page_locale %} - Returns full locale (e.g., ja_JP, en_US)
{% seo_head %} - Automatically includes og:locale meta tag

Available Locales

Locale	Language
`ja_JP`	日本語 (日本)
`en_US`	English (US)
`en_GB`	English (UK)
`zh_CN`	中文 (简体)
`zh_TW`	中文 (繁體)
`ko_KR`	한국어
`fr_FR`	Français (France)
`de_DE`	Deutsch (Deutschland)
`es_ES`	Español (España)
`pt_BR`	Português (Brasil)

Set the default locale in Settings > SEO Settings, then override per-page using the SEOPageMixin.

robots.txt Management

Configure robots.txt from Wagtail admin without editing files.

Setup

Add wagtail-herald URLs to your urls.py:

from django.urls import include, path

urlpatterns = [
    path('', include('wagtail_herald.urls')),
    # ... other urls
]

Configuration

Go to Settings > SEO Settings and edit the robots.txt content:

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /search/

Sitemap: https://example.com/sitemap.xml

If left empty, a sensible default is generated (allow all crawlers, include sitemap URL).

ads.txt Management

Configure ads.txt (Authorized Digital Sellers) from Wagtail admin without editing files.

Setup

Include wagtail-herald URLs in your urls.py (same as robots.txt):

from django.urls import include, path

urlpatterns = [
    path('', include('wagtail_herald.urls')),
    # ... other urls
]

Configuration

Go to Settings > SEO Settings and edit the ads.txt content:

google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0

Unlike robots.txt, if the ads.txt field is left empty, the /ads.txt endpoint returns a 404 response rather than generating default content.

security.txt Management

Configure security.txt (RFC 9116) from Wagtail admin without editing files. This file helps security researchers report vulnerabilities through the standardized /.well-known/security.txt path.

Setup

Include wagtail-herald URLs in your urls.py (same as robots.txt and ads.txt):

from django.urls import include, path

urlpatterns = [
    path('', include('wagtail_herald.urls')),
    # ... other urls
]

Configuration

Go to Settings > SEO Settings and edit the security.txt content. Per RFC 9116, the Contact and Expires fields are required:

Contact: mailto:security@example.com
Expires: 2026-12-31T23:59:59z
Preferred-Languages: en, ja
Canonical: https://example.com/.well-known/security.txt

If the security.txt field is left empty, the /.well-known/security.txt endpoint returns a 404 response.

Requirements

Python	Django	Wagtail
3.10+	4.2, 5.1, 5.2	6.4, 7.0, 7.2

Documentation

Contributing Guide

Project Links

Related Projects

wagtail-seo - SEO optimization by CodeRed
wagtail-metadata - Meta tags by Neon Jungle
wagtail-schema.org - Schema.org by Neon Jungle

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

BSD 3-Clause License. See LICENSE for details.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.10.2

Mar 28, 2026

0.10.1

Mar 26, 2026

0.10.0

Mar 26, 2026

This version

0.9.0

Mar 26, 2026

0.8.0

Mar 20, 2026

0.7.0

Mar 18, 2026

0.6.0

Mar 3, 2026

0.5.1

Feb 19, 2026

0.5.0

Feb 18, 2026

0.4.1

Dec 19, 2025

0.4.0

Dec 19, 2025

0.3.0

Dec 18, 2025

0.2.0

Dec 18, 2025

0.1.0

Dec 18, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wagtail_herald-0.9.0.tar.gz (138.8 kB view details)

Uploaded Mar 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

wagtail_herald-0.9.0-py3-none-any.whl (108.0 kB view details)

Uploaded Mar 26, 2026 Python 3

File details

Details for the file wagtail_herald-0.9.0.tar.gz.

File metadata

Download URL: wagtail_herald-0.9.0.tar.gz
Upload date: Mar 26, 2026
Size: 138.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for wagtail_herald-0.9.0.tar.gz
Algorithm	Hash digest
SHA256	`78b28e6b76b13aec4f7d658fab4950c1cebf1e73360c48d3a6f55c4e4134b682`
MD5	`c53f7f6cd63c8a6b09ece5b69630345c`
BLAKE2b-256	`ec42f289267fc660b98192ea5e57495c8d650f42eef10187357ecc50d208f438`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_herald-0.9.0.tar.gz:

Publisher: publish.yml on kkm-horikawa/wagtail-herald

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wagtail_herald-0.9.0.tar.gz
- Subject digest: 78b28e6b76b13aec4f7d658fab4950c1cebf1e73360c48d3a6f55c4e4134b682
- Sigstore transparency entry: 1186078500
- Sigstore integration time: Mar 26, 2026
Source repository:
- Permalink: kkm-horikawa/wagtail-herald@5f313a6959844f25ed86ca3a211fa11dd4e59973
- Branch / Tag: refs/tags/v0.9.0
- Owner: https://github.com/kkm-horikawa
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@5f313a6959844f25ed86ca3a211fa11dd4e59973
- Trigger Event: push

File details

Details for the file wagtail_herald-0.9.0-py3-none-any.whl.

File metadata

Download URL: wagtail_herald-0.9.0-py3-none-any.whl
Upload date: Mar 26, 2026
Size: 108.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for wagtail_herald-0.9.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`87645c2226eaa43fbdacea4a3154783f6e7ece35a53622ef3b958d22b995e2a4`
MD5	`5523f4fd58dde1246a0b815933f567db`
BLAKE2b-256	`7f1245666e901499e3da43b7094e9cee3dd6edca50bf8054a7d0a13f12e65ab7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_herald-0.9.0-py3-none-any.whl:

Publisher: publish.yml on kkm-horikawa/wagtail-herald

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wagtail_herald-0.9.0-py3-none-any.whl
- Subject digest: 87645c2226eaa43fbdacea4a3154783f6e7ece35a53622ef3b958d22b995e2a4
- Sigstore transparency entry: 1186078516
- Sigstore integration time: Mar 26, 2026
Source repository:
- Permalink: kkm-horikawa/wagtail-herald@5f313a6959844f25ed86ca3a211fa11dd4e59973
- Branch / Tag: refs/tags/v0.9.0
- Owner: https://github.com/kkm-horikawa
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@5f313a6959844f25ed86ca3a211fa11dd4e59973
- Trigger Event: push

wagtail-herald 0.9.0

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

wagtail-herald

Philosophy

Key Features

Installation

Quick Start

1. Add Template Tags

2. Configure Site Settings

3. Add SEO Mixin to Pages (Optional)

4. Override SEO per Sub-route (RoutablePageMixin)

Supported Schema Types

Site-wide (Automatic)

Page-selectable

Automatic

Output Example

{% seo_head %} Output

{% seo_body %} Output

{% seo_schema %} Output

Configuration

Site Settings (Admin UI)

Django Settings (Optional)

Locale Support

Use Case: Mixed Language Content

Available Locales

robots.txt Management

Setup

Configuration

ads.txt Management

Setup

Configuration

security.txt Management

Setup

Configuration

Requirements

Documentation

Project Links

Related Projects

Contributing

License

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

`{% seo_head %}` Output

`{% seo_body %}` Output

`{% seo_schema %}` Output