Skip to content
Wagtail Wagtail Documentation
  • Getting started
    • Your first Wagtail site
    • Quick install
    • Demo site
    • Integrating Wagtail into a Django project
    • The Zen of Wagtail
  • Tutorial
    • Customize your home page
    • Create a footer for all pages
    • Create editable footer text with Wagtail Snippets
    • Set up site menu for linking to the homepage and other pages
    • Style and improve user experience
    • Create contact page
    • Create a portfolio page
    • Add search to your site
    • Deploy your site
  • Usage guide
    • Page models
    • Writing templates
    • How to use images in templates
    • Search
      • Indexing
      • Searching
      • Backends
    • Snippets
      • Registering snippets
      • Rendering snippets
      • Optional features
      • Customizing admin views for snippets
    • How to use StreamField for mixed content
    • Permissions
  • Advanced
    • Images
      • Images overview
      • Generating renditions in Python
      • Animated GIF support
      • Image file formats
      • Custom image models
      • Changing rich text representation
      • Feature detection
      • Dynamic image serve view
      • Focal points
      • Title generation on upload
    • Documents
      • Documents overview
      • Custom document model
      • Custom document upload form
      • Storing and serving
      • Title generation on upload
      • Testing documents
    • Icons
    • Embedded content
    • Tagging
    • How to add Wagtail into an existing Django project
    • Performance
    • Internationalization
    • Private pages
    • Customizing Wagtail
      • Customizing the editing interface
      • Customizing page listings
      • Customizing admin templates
      • Custom user models
      • How to build custom StreamField blocks
      • Defining custom base page models
    • Third-party tutorials
    • Testing your Wagtail site
    • Wagtail API
      • Wagtail API v2 configuration guide
      • Wagtail API v2 usage guide
      • Wagtail API v3
        • v3 API authentication
        • Configuring fields
        • Pages
        • Workflows
        • Images
        • Documents
        • Snippets
        • Redirects
        • StreamField and relations in the API
        • Rich text in the API
        • Sites
        • Locales and translations
        • Schema discovery
        • v3 API reference
        • Migrating from the v2 API
      • How to build your own API with Django Ninja
    • How to build a site with AMP support
    • Accessibility considerations
    • Sustainability considerations
    • About StreamField BoundBlocks and values
    • Multi-site, multi-instance and multi-tenancy
    • How to use a redirect with Form builder to prevent double submission
    • StreamField migrations
    • StreamField validation
    • Manage the reference index
    • Headless support
    • Content personalization
    • How to vary page responses
  • Extending
    • Creating admin views
    • Generic views
    • Template components
    • Using forms in admin views
    • Adding reports
    • Adding new Task types
    • Audit log
    • Customizing the user account settings form
    • Customizing group edit/create views
    • Custom image filters
    • Extending client-side behavior
    • Accessing the editor programmatically
    • Accessing panels from client-side code
    • Rich text internals
    • Extending the Draftail editor
    • Adding custom bulk actions
    • Adapting reusable apps to support custom base page models
  • Reference
    • Pages
      • Theory
      • Recipes
      • Page QuerySet reference
    • StreamField reference
      • StreamField block reference
      • Form widget client-side API
      • StreamField data migration reference
    • Contrib modules
      • Settings models
      • Form builder
        • Form builder customization
      • Sitemap generator
      • Frontend cache invalidator
      • RoutablePageMixin
      • Promoted search results
      • Simple translation
      • TableBlock
      • Typed table block
      • Redirects
      • Legacy richtext
    • Admin UI reference
      • UI components
      • JavaScript components
      • Tables
    • Management commands
    • Model reference
    • Hooks
    • Signals
    • Settings
    • The project template
    • Permissions
    • Jinja2 template support
    • Panels
    • Viewsets
  • Deployment & hosting
  • Packages
  • Support
  • Editor’s guide
  • Contributing
    • Your first contribution
    • Setting up a development environment
    • API development
    • General coding guidelines
    • Python coding guidelines
    • UI coding guidelines
    • Documentation guidelines
    • Writing documentation
    • Translations
    • Reporting security issues
    • Issue tracking
    • Committing code
  • Release notes
    • Upgrading Wagtail
    • Wagtail’s release process
    • Wagtail 8.2 release notes - IN DEVELOPMENT
    • Wagtail 8.1.1 release notes - IN DEVELOPMENT
    • Wagtail 8.1 release notes
    • Wagtail 8.0.1 release notes
    • Wagtail 8.0 release notes
    • Wagtail 7.4.5 release notes - IN DEVELOPMENT
    • Wagtail 7.4.4 release notes
    • Wagtail 7.4.3 release notes
    • Wagtail 7.4.2 release notes
    • Wagtail 7.4.1 release notes
    • Wagtail 7.4 (LTS) release notes
    • Wagtail 7.3.4 release notes
    • Wagtail 7.3.3 release notes
    • Wagtail 7.3.2 release notes
    • Wagtail 7.3.1 release notes
    • Wagtail 7.3 release notes
    • Wagtail 7.2.3 release notes
    • Wagtail 7.2.2 release notes
    • Wagtail 7.2.1 release notes
    • Wagtail 7.2 release notes
    • Wagtail 7.1.3 release notes
    • Wagtail 7.1.2 release notes
    • Wagtail 7.1.1 release notes
    • Wagtail 7.1 release notes
    • Wagtail 7.0.10 release notes
    • Wagtail 7.0.9 release notes
    • Wagtail 7.0.8 release notes
    • Wagtail 7.0.7 release notes
    • Wagtail 7.0.6 release notes
    • Wagtail 7.0.5 release notes
    • Wagtail 7.0.4 release notes
    • Wagtail 7.0.3 release notes
    • Wagtail 7.0.2 release notes
    • Wagtail 7.0.1 release notes
    • Wagtail 7.0 (LTS) release notes
    • Wagtail 6.4.2 release notes
    • Wagtail 6.4.1 release notes
    • Wagtail 6.4 release notes
    • Wagtail 6.3.9 release notes - IN DEVELOPMENT
    • Wagtail 6.3.8 release notes
    • Wagtail 6.3.7 release notes
    • Wagtail 6.3.6 release notes
    • Wagtail 6.3.5 release notes
    • Wagtail 6.3.4 release notes
    • Wagtail 6.3.3 release notes
    • Wagtail 6.3.2 release notes
    • Wagtail 6.3.1 release notes
    • Wagtail 6.3 (LTS) release notes
    • Wagtail 6.2.4 release notes
    • Wagtail 6.2.3 release notes
    • Wagtail 6.2.2 release notes
    • Wagtail 6.2.1 release notes
    • Wagtail 6.2 release notes
    • Wagtail 6.1.3 release notes
    • Wagtail 6.1.2 release notes
    • Wagtail 6.1.1 release notes
    • Wagtail 6.1 release notes
    • Wagtail 6.0.6 release notes
    • Wagtail 6.0.5 release notes
    • Wagtail 6.0.4 release notes
    • Wagtail 6.0.3 release notes
    • Wagtail 6.0.2 release notes
    • Wagtail 6.0.1 release notes
    • Wagtail 6.0 release notes
    • Wagtail 5.2.8 release notes
    • Wagtail 5.2.7 release notes
    • Wagtail 5.2.6 release notes
    • Wagtail 5.2.5 release notes
    • Wagtail 5.2.4 release notes
    • Wagtail 5.2.3 release notes
    • Wagtail 5.2.2 release notes
    • Wagtail 5.2.1 release notes
    • Wagtail 5.2 (LTS) release notes
    • Wagtail 5.1.3 release notes
    • Wagtail 5.1.2 release notes
    • Wagtail 5.1.1 release notes
    • Wagtail 5.1 release notes
    • Wagtail 5.0.5 release notes
    • Wagtail 5.0.4 release notes
    • Wagtail 5.0.3 release notes
    • Wagtail 5.0.2 release notes
    • Wagtail 5.0.1 release notes
    • Wagtail 5.0 release notes
    • Wagtail 4.2.4 release notes
    • Wagtail 4.2.3 release notes
    • Wagtail 4.2.2 release notes
    • Wagtail 4.2.1 release notes
    • Wagtail 4.2 release notes
    • Wagtail 4.1.9 release notes
    • Wagtail 4.1.8 release notes
    • Wagtail 4.1.7 release notes
    • Wagtail 4.1.6 release notes
    • Wagtail 4.1.5 release notes
    • Wagtail 4.1.4 release notes
    • Wagtail 4.1.3 release notes
    • Wagtail 4.1.2 release notes
    • Wagtail 4.1.1 release notes
    • Wagtail 4.1 (LTS) release notes
    • Wagtail 4.0.4 release notes
    • Wagtail 4.0.2 release notes
    • Wagtail 4.0.1 release notes
    • Wagtail 4.0 release notes
    • Wagtail 3.0.3 release notes
    • Wagtail 3.0.2 release notes
    • Wagtail 3.0.1 release notes
    • Wagtail 3.0 release notes
    • Wagtail 2.16.3 release notes
    • Wagtail 2.16.2 release notes
    • Wagtail 2.16.1 release notes
    • Wagtail 2.16 release notes
    • Wagtail 2.15.6 release notes
    • Wagtail 2.15.5 release notes
    • Wagtail 2.15.4 release notes
    • Wagtail 2.15.3 release notes
    • Wagtail 2.15.2 release notes
    • Wagtail 2.15.1 release notes
    • Wagtail 2.15 (LTS) release notes
    • Wagtail 2.14.2 release notes
    • Wagtail 2.14.1 release notes
    • Wagtail 2.14 release notes
    • Wagtail 2.13.5 release notes
    • Wagtail 2.13.4 release notes
    • Wagtail 2.13.3 release notes
    • Wagtail 2.13.2 release notes
    • Wagtail 2.13.1 release notes
    • Wagtail 2.13 release notes
    • Wagtail 2.12.6 release notes
    • Wagtail 2.12.5 release notes
    • Wagtail 2.12.4 release notes
    • Wagtail 2.12.3 release notes
    • Wagtail 2.12.2 release notes
    • Wagtail 2.12.1 release notes
    • Wagtail 2.12 release notes
    • Wagtail 2.11.9 release notes
    • Wagtail 2.11.8 release notes
    • Wagtail 2.11.7 release notes
    • Wagtail 2.11.6 release notes
    • Wagtail 2.11.5 release notes
    • Wagtail 2.11.4 release notes
    • Wagtail 2.11.3 release notes
    • Wagtail 2.11.2 release notes
    • Wagtail 2.11.1 release notes
    • Wagtail 2.11 (LTS) release notes
    • Wagtail 2.10.2 release notes
    • Wagtail 2.10.1 release notes
    • Wagtail 2.10 release notes
    • Wagtail 2.9.3 release notes
    • Wagtail 2.9.2 release notes
    • Wagtail 2.9.1 release notes
    • Wagtail 2.9 release notes
    • Wagtail 2.8.2 release notes
    • Wagtail 2.8.1 release notes
    • Wagtail 2.8 release notes
    • Wagtail 2.7.4 release notes
    • Wagtail 2.7.3 release notes
    • Wagtail 2.7.2 release notes
    • Wagtail 2.7.1 release notes
    • Wagtail 2.7 (LTS) release notes
    • Wagtail 2.6.3 release notes
    • Wagtail 2.6.2 release notes
    • Wagtail 2.6.1 release notes
    • Wagtail 2.6 release notes
    • Wagtail 2.5.2 release notes
    • Wagtail 2.5.1 release notes
    • Wagtail 2.5 release notes
    • Wagtail 2.4 release notes
    • Wagtail 2.3 (LTS) release notes
    • Wagtail 2.2.2 release notes
    • Wagtail 2.2.1 release notes
    • Wagtail 2.2 release notes
    • Wagtail 2.1.3 release notes
    • Wagtail 2.1.2 release notes
    • Wagtail 2.1.1 release notes
    • Wagtail 2.1 release notes
    • Wagtail 2.0.2 release notes
    • Wagtail 2.0.1 release notes
    • Wagtail 2.0 release notes
    • Wagtail 1.13.4 release notes
    • Wagtail 1.13.3 release notes
    • Wagtail 1.13.2 release notes
    • Wagtail 1.13.1 release notes
    • Wagtail 1.13 (LTS) release notes
    • Wagtail 1.12.6 release notes
    • Wagtail 1.12.5 release notes
    • Wagtail 1.12.4 release notes
    • Wagtail 1.12.3 release notes
    • Wagtail 1.12.2 release notes
    • Wagtail 1.12.1 release notes
    • Wagtail 1.12 (LTS) release notes
    • Wagtail 1.11.1 release notes
    • Wagtail 1.11 release notes
    • Wagtail 1.10.1 release notes
    • Wagtail 1.10 release notes
    • Wagtail 1.9.1 release notes
    • Wagtail 1.9 release notes
    • Wagtail 1.8.2 release notes
    • Wagtail 1.8.1 release notes
    • Wagtail 1.8 (LTS) release notes
    • Wagtail 1.7 release notes
    • Wagtail 1.6.3 release notes
    • Wagtail 1.6.2 release notes
    • Wagtail 1.6.1 release notes
    • Wagtail 1.6 release notes
    • Wagtail 1.5.3 release notes
    • Wagtail 1.5.2 release notes
    • Wagtail 1.5.1 release notes
    • Wagtail 1.5 release notes
    • Wagtail 1.4.6 release notes
    • Wagtail 1.4.5 release notes
    • Wagtail 1.4.4 release notes
    • Wagtail 1.4.3 release notes
    • Wagtail 1.4.2 release notes
    • Wagtail 1.4.1 release notes
    • Wagtail 1.4 (LTS) release notes
    • Wagtail 1.3.1 release notes
    • Wagtail 1.3 release notes
    • Wagtail 1.2 release notes
    • Wagtail 1.1 release notes
    • Wagtail 1.0 release notes
    • Wagtail 0.8.10 release notes
    • Wagtail 0.8.8 release notes
    • Wagtail 0.8.7 release notes
    • Wagtail 0.8.6 release notes
    • Wagtail 0.8.5 release notes
    • Wagtail 0.8.4 release notes
    • Wagtail 0.8.3 release notes
    • Wagtail 0.8.1 release notes
    • Wagtail 0.8 (LTS) release notes
    • Wagtail 0.7 release notes
    • Wagtail 0.6 release notes
    • Wagtail 0.5 release notes
    • Wagtail 0.4.1 release notes
    • Wagtail 0.4 release notes
  1. Docs
  2. Reference
  3. Contrib modules
  4. Promoted search results
Edit on GitHub View source

Promoted search results¶

The searchpromotions module provides the models and user interface for managing “Promoted search results” and displaying them in a search results page.

“Promoted search results” allow editors to explicitly link relevant content to search terms, so results pages can contain curated content in addition to results from the search engine.

Installation¶

The searchpromotions module is not enabled by default. To install it, add wagtail.contrib.search_promotions to INSTALLED_APPS in your project’s Django settings file.

INSTALLED_APPS = [
    ...

    'wagtail.contrib.search_promotions',
]

This app contains migrations so make sure you run the migrate django-admin command after installing.

Usage¶

Once installed, a new menu item called “Promoted search results” should appear in the “Settings” menu. This is where you can assign pages to popular search terms.

Displaying on a search results page¶

To retrieve a list of promoted search results for a particular search query, you can use the {% get_search_promotions %} template tag from the wagtailsearchpromotions_tags templatetag library:

{% load wagtailcore_tags wagtailsearchpromotions_tags %}

...

{% get_search_promotions search_query as search_promotions %}

<ul>
    {% for search_promotion in search_promotions %}
        {% if search_promotion.page %}
            <li>
                <a href="{% pageurl search_promotion.page %}">
                    <h2>{{ search_promotion.page.title }}</h2>
                    <p>{{ search_promotion.description }}</p>
                </a>
            </li>
        {% else %}
            <li>
                <a href="{{ search_promotion.external_link_url }}">
                    <h2>{{ search_promotion.external_link_text }}</h2>
                    <p>{{ search_promotion.description }}</p>
                </a>
            </li>
        {% endif %}
    {% endfor %}
</ul>

Managing stored search queries¶

The searchpromotions module keeps a log of search queries as well as the number of daily hits through the Query and QueryDailyHits models.

class wagtail.contrib.search_promotions.models.Query¶
classmethod get(query_string)¶

Retrieves a stored search query or creates a new one if it doesn’t exist.

add_hit(date=None)¶

Records another daily hit for a search query by creating a new record or incrementing the number of hits for an existing record. Defaults to using the current date but an optional date parameter can be passed in.

Example search view¶

Here’s an example Django view for a search page that records a hit for the search query:

from django.template.response import TemplateResponse

from wagtail.models import Page
from wagtail.contrib.search_promotions.models import Query


def search(request):
    search_query = request.GET.get("query", None)

    if search_query:
        search_results = Page.objects.live().search(search_query)
        query = Query.get(search_query)

        # Record hit
        query.add_hit()
    else:
        search_results = Page.objects.none()

    return TemplateResponse(
        request,
        "search/search.html",
        {
            "search_query": search_query,
            "search_results": search_results,
        },
    )

Management Commands¶

searchpromotions_garbage_collect¶

./manage.py searchpromotions_garbage_collect

On high traffic websites, the stored queries and daily hits logs may get large and you may want to clean out old records. This command cleans out all search query logs that are more than one week old (or a number of days configurable through the WAGTAILSEARCH_HITS_MAX_AGE setting).

← RoutablePageMixin Simple translation  →

Page contents

  • Promoted search results
    • Installation
    • Usage
      • Displaying on a search results page
      • Managing stored search queries
        • wagtail.contrib.search_promotions.models.Query
          • wagtail.contrib.search_promotions.models.Query.get()
          • wagtail.contrib.search_promotions.models.Query.add_hit()
        • Example search view
    • Management Commands
      • searchpromotions_garbage_collect
  • Features
  • About Wagtail
  • Services
  • Blog
  • Packages
  • Developers
© Copyright 2026, Wagtail core team and contributors. BSD license
Created using Sphinx Wagtail Theme 6.6.0 and Sphinx 9.2.0