https://badge.fury.io/py/wagtail-metadata-mixin.svg https://img.shields.io/pypi/pyversions/wagtail-metadata-mixin.svg https://img.shields.io/pypi/djversions/wagtail-metadata-mixin.svg https://github.com/bashu/wagtail-metadata-mixin/actions/workflows/test.yml/badge.svg

OpenGraph, Twitter Card and Schema.org snippet tags for Wagtail CMS pages.

The current version is tested for compatiblily with the following:

  • Wagtail versions 6.3 to 7.4

  • Django versions 5.2, 6.0 and 6.1

  • Python versions 3.10 to 3.14

Authored by Basil Shubin, and some great contributors.

Installation

First install the module, preferably in a virtual environment. It can be installed from PyPI:

pip install wagtail-metadata-mixin

Requirements

You must have django-meta installed and configured, see the django-meta documentation for details and setup instructions.

Setup

First make sure the project is configured for django-meta.

Then add the following settings:

INSTALLED_APPS += (
    'wagtailmetadata',
)

and just include meta/meta.html template in your templates

{% load meta %}

<html {% meta_namespaces_schemaorg %}>
    <head {% meta_namespaces %}>
        {% include "meta/meta.html" %}
    </head>
    <body>...</body>
</html>

Check django-meta documentation for more details.

Usage

# models.py

from wagtail.models import Page, PageBase

from wagtailmetadata.models import MetadataPageMixin

# ensure MetadataPageMixin class goes before Page class
class CustomPage(MetadataPageMixin, Page):
    schemaorg_type = "Page"

    promote_panels = Page.promote_panels + MetadataPageMixin.panels

MetadataPageMixin already provides sensible defaults for every field (title uses seo_title or title, description uses search_description, image uses search_image, and so on). There are two ways to customise them on your own page.

Overriding the get_meta_* methods

The most common approach – override the relevant method(s), the same way MetadataPageMixin itself overrides MetadataMixin:

class ArticlePage(MetadataPageMixin, Page):
    body = RichTextField(blank=True)

    def get_meta_description(self):
        return self.search_description or Truncator(strip_tags(self.body)).words(30)

    def get_meta_twitter_type(self):
        return "summary_large_image"

Overriding _metadata

If you just want to point an existing field at a different attribute or method, without writing a whole new get_meta_* method, extend _metadata instead:

class ArticlePage(MetadataPageMixin, Page):
    _metadata = {
        **MetadataPageMixin._metadata,
        # use the actual publish date, instead of the latest (possibly
        # unpublished) revision's timestamp
        "modified_time": "last_published_at",
    }

Both approaches can be freely combined, and work the same way for _schema and for adding custom tags/properties.

Schema.org support

wagtail-metadata-mixin provides full support for schema.org in JSON-LD format, out of the box, through the _schema attribute.

In the same way as the basic _metadata attribute, _schema resolves and builds the per-page Schema.org representation. As per _metadata, its values can be the name of a method, property or attribute available on the class. MetadataPageMixin already ships with a sensible default:

_schema = {
    "name": "get_meta_title",
    "headline": "get_meta_title",
    "description": "get_meta_description",
    "image": "get_meta_image",
    "url": "get_meta_url",
    "author": "get_author_name",
    "datePublished": "published_time",
    "dateModified": "latest_revision_created_at",
}

You can create your own schema, extending or overriding the default one, without having to touch MetadataPageMixin itself:

class ArticlePage(MetadataPageMixin, Page):
    schemaorg_type = "Article"

    _schema = {
        **MetadataPageMixin._schema,
        "articleSection": "get_categories",
        "keywords": "get_keywords",
    }

    def get_categories(self):
        return list(self.categories.values_list("name", flat=True))

    def get_keywords(self):
        return self.get_meta_keywords()

Check django-meta’s schema.org documentation for more details.

Adding custom tags / properties

Custom tags/properties can be added to your page without having to override the meta/meta.html template, by adding them to the _metadata attribute, as per the other properties.

You can provide either a static value (see extra_props below), or the name of a method which will return the value at runtime (see extra_custom_props):

class CustomPage(MetadataPageMixin, Page):
    _metadata = {
        **MetadataPageMixin._metadata,
        "extra_props": {
            "designer": "Pablo Picasso",
        },
        "extra_custom_props": "get_custom_props",
    }

    def get_custom_props(self):
        return [
            ("property", "og:type", "music.song"),
            ("property", "music:duration", "3"),
        ]

extra_props renders a <meta> tag per key/value pair, using the key as the name attribute:

<meta name="designer" content="Pablo Picasso">

extra_custom_props takes a list of (attribute, name, value) tuples, letting you pick the attribute used (e.g. property for Open Graph tags):

<meta property="og:type" content="music.song">
<meta property="music:duration" content="3">

Check django-meta’s extra tags documentation for more details.

Customising the search image rendition

By default, the search image rendition is set to fill-800x450.

If you wish to use a different rendition, you can set the WAGTAILMETADATA_SEARCH_IMAGE_RENDITION setting to change the filter used. e.g.

WAGTAILMETADATA_SEARCH_IMAGE_RENDITION = "fill-1200x630"

Contributing

If you like this module, forked it, or would like to improve it, please let us know! Pull requests are welcome too. :-)

License

wagtail-metadata-mixin is released under the MIT license.

Changes

3.0.1 (2026-08-15)

  • Added og/twitter/schemaorg title and description fields, JSON-LD toggle, and OG type/app_id/profile_id/publisher/author_url fields, matching django-meta’s current API.

  • Added full support for schema.org in JSON-LD format via the _schema attribute.

  • Fixed get_meta_image_width()/get_meta_image_height() to build off a rendition, consistent with get_meta_image().

  • Fixed get_meta_site_name(), get_domain() and build_absolute_uri() to no longer crash silently when used on a non-Page model.

3.0.0 (2026-08-15)

  • Bumped requirements: Wagtail 6.3+, Django 5.2/6.0/6.1, Python 3.10+, django-meta 2.5+.

2.0.2 (2021-11-29)

  • Fixed stupid typo.

2.0.1 (2021-11-29)

  • Added ru translation.

2.0.0 (2021-11-28)

  • Added Wagtail 2.15 and Django 3.2 support.

  • Dropped Wagtail 2.7 support.

Project links

Data verified by PyPI on Aug 15, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bashu from gravatar.com bashu

Credits

Author/Maintainer: Basil Shubin

GitHub Statistics

Data verified by PyPI on Aug 15, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

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

Source Distribution

wagtail_metadata_mixin-3.0.1.tar.gz (12.6 kB view details)

Uploaded Source

Built Distribution

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

wagtail_metadata_mixin-3.0.1-py3-none-any.whl (14.1 kB view details)

Uploaded Python 3

File details

Details for the file wagtail_metadata_mixin-3.0.1.tar.gz.

File metadata

  • Download URL: wagtail_metadata_mixin-3.0.1.tar.gz
  • Upload date:
  • Size: 12.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for wagtail_metadata_mixin-3.0.1.tar.gz
Algorithm Hash digest
SHA256 8603c33ad8a30518819270c3328a728961ebb1dec4142cf0b8d4eb81dbe79af0
MD5 44e8eecc16676e460db64f1e3a1fec14
BLAKE2b-256 2d7e7b0034177a04d5168899661c35259555bde6fd16159e9667a684c6059fb0

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_metadata_mixin-3.0.1.tar.gz:

Publisher: release.yml on bashu/wagtail-metadata-mixin

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

File details

Details for the file wagtail_metadata_mixin-3.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for wagtail_metadata_mixin-3.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 0bb3ce2f74282d49812c6e031f5d49da12d832ec43ccd465bd9cf90eb59851f2
MD5 da65d9dca64d37b2c8d7e55eab918ad1
BLAKE2b-256 bcd7f22418436303f43b9e720b138bb34fdbfbea94690de569084a2c40dff3a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_metadata_mixin-3.0.1-py3-none-any.whl:

Publisher: release.yml on bashu/wagtail-metadata-mixin

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

Release history Release notifications | RSS feed

This release

3.0.1 This release

2 files

3.0.0

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

0.1.1

2 files

0.1.0

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page