Wagtail

https://docs.wagtail.org/en/stable/
Admin
Wagtail is an open source CMS written in Python and built on the Django web framework.
Tokens:616,299
Snippets:5,078
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start development server

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/tutorial.html

Start the development server. After it starts, go to http://127.0.0.1:8000 to see Wagtail's welcome page. The URL may differ depending on your setup; read the console output to determine the correct URL.

```bash
python manage.py runserver
```

--------------------------------

### Set up and run the Wagtail project

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/quick_install.html

Sets up the generated project: installs dependencies, applies migrations, creates a superuser, and starts the development server.

```bash
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

```

--------------------------------

### specific() example: get specific instances efficiently

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Efficiently gets all the specific items for the queryset, using the minimum number of queries. This example gets the specific instance of all children of the homepage.

```python
# Get the specific instance of all children of the hompage,
# in a minimum number of database queries.
homepage.get_children().specific()

```

--------------------------------

### Example request for GET /api/v3/images/

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Shows an HTTP GET request to list images. The request includes the path and host header.

```http
GET /api/v3/images/ HTTP/1.1
Host: example.com

```

--------------------------------

### GET /api/v3/sites/ - List sites request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request to list sites. Accepts limit and offset query parameters. Returns 200 OK.

```http
GET /api/v3/sites/ HTTP/1.1
Host: example.com

```

--------------------------------

### not_descendant_of() method example

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Gets EventPages that are not descendants of the archived_events_index page. This is the example for the not_descendant_of() method.

```python
# Get EventPages that are not under the archived_events Page
non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
```

--------------------------------

### Get language info for language_code

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/i18n.html

Gets language information for the current language_code, same as in the basic example.

```django
{% get_language_info for language_code as lang %}

```

--------------------------------

### Initialize project with custom template

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/project_template.html

Use the --template option to specify a custom project template via URL.

```bash
wagtail start myproject --template=https://github.com/githubuser/wagtail-awesome-template/archive/main.zip
```

--------------------------------

### not_ancestor_of() method example

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Gets sections that are not ancestors of the current page but are children of the homepage. This is the example for the not_ancestor_of() method.

```python
# Get the other sections
other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
```

--------------------------------

### Install wagtail.contrib.styleguide in INSTALLED_APPS

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/ui_guidelines.html

Add the styleguide module to your Django settings to install it. This adds a 'Styleguide' item to the Settings menu in the admin.

```python
INSTALLED_APPS = (
    # ...
    "wagtail.contrib.styleguide",
    # ...
)

```

--------------------------------

### Set MEDIA_ROOT and MEDIA_URL

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/integrating_into_django.html

Add MEDIA_ROOT and MEDIA_URL settings if your project doesn't have them already.

```python
MEDIA_ROOT = BASE_DIR / "media"
MEDIA_URL = "/media/"
```

--------------------------------

### GET /api/v3/pages/find/ request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request for the GET /api/v3/pages/find/ endpoint. Uses the Host header to specify the domain.

```http
GET /api/v3/pages/find/ HTTP/1.1
Host: example.com

```

--------------------------------

### Create and run database migrations

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/tutorial.html

Run these commands to create and apply migrations after adding a new model.

```bash
python manage.py makemigrations
python manage.py migrate

```

--------------------------------

### GET /api/v3/pages/{page_id}/ request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request for the GET /api/v3/pages/{page_id}/ endpoint. Uses the Host header to specify the domain.

```http
GET /api/v3/pages/{page_id}/ HTTP/1.1
Host: example.com

```

--------------------------------

### Preview compiled docs with python -m http.server

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Starts a simple HTTP server to preview the compiled documentation in a web browser at http://localhost:8080/.

```bash
# Starting from the wagtail root directory:

cd docs/_build/html/
python -m http.server 8080

```

--------------------------------

### Enable previews for settings with PreviewableMixin

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/contrib/settings.html

Shows how to enable live previews for settings models by inheriting from PreviewableMixin and overriding get_preview_template() or serve_preview(). The example defines a generic setting with a custom preview template and a site-specific setting with multiple preview modes that reuses Page templates and adds a Page instance to the preview context.

```python
from wagtail.contrib.settings.models import (
    BaseGenericSetting,
    BaseSiteSetting,
    register_setting,
)
from wagtail.models import PreviewableMixin

from myproject.blog.models import BlogPage
from myproject.home.models import HomePage


@register_setting
class GenericSocialMediaSettings(PreviewableMixin, BaseGenericSetting):
    def get_preview_template(self, request, mode_name):
        # Custom template specifically for this setting's preview
        return "settings/generic/social_media.html"


@register_setting
class SiteSpecificSocialMediaSettings(PreviewableMixin, BaseSiteSetting):
    preview_modes = [("home", "Home page"), ("blog", "Blog page")]
    _models_for_preview = {
        "home": HomePage,
        "blog": BlogPage,
    }

    def get_preview_context(self, request, mode_name):
        # Add a Page instance to the context for the preview
        context = super().get_preview_context(request, mode_name)
        context["page"] = (
            self._models_for_preview[mode_name]
            .objects.descendant_of(self.site.root_page, inclusive=True)
            .first()
        )
        return context

    def get_preview_template(self, request, mode_name):
        # Reuse the Page model's template for the preview
        return self._models_for_preview[mode_name].template
```

--------------------------------

### Example URL prefixes with default language bypass

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/i18n.html

Example of resulting URL prefixes when prefix_default_language is False: only the French version gets a prefix.

```text
- /search/
- /fr/search/

```

--------------------------------

### Example request for GET /api/v3/images/{image_id}/

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Shows an HTTP GET request to retrieve a single image by its ID. The image_id path parameter is required.

```http
GET /api/v3/images/{image_id}/ HTTP/1.1
Host: example.com

```

--------------------------------

### Create a Wagtail page in tests with root and Site setup

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/testing.html

Sets up a root page, a default Site, and a HomePage before creating a MyPage instance as a child. Use this in a WagtailPageTestCase to test page URLs and responses.

```python
from wagtail.models import Page, Site
from wagtail.rich_text import RichText
from wagtail.test.utils import WagtailPageTestCase

from home.models import HomePage, MyPage


class MyPageTest(WagtailPageTestCase):
    @classmethod
    def setUpTestData(cls):
        root = Page.get_first_root_node()
        Site.objects.create(
            hostname="testserver",
            root_page=root,
            is_default_site=True,
            site_name="testserver",
        )
        home = HomePage(title="Home")
        root.add_child(instance=home)
        cls.page = MyPage(
            title="My Page",
            slug="mypage",
        )
        home.add_child(instance=cls.page)

    def test_get(self):
        response = self.client.get(self.page.url)
        self.assertEqual(response.status_code, 200)
```

--------------------------------

### GET /api/v3/redirects/{redirect_id}/ - Redirect detail request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request to get a redirect detail. Requires redirect_id path parameter. Returns 200 OK.

```http
GET /api/v3/redirects/{redirect_id}/ HTTP/1.1
Host: example.com

```

--------------------------------

### Run database migrations

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/tutorial.html

Create the database and match database tables with project models. Run this command every time you alter your model, for example when adding a field.

```bash
python manage.py migrate
```

--------------------------------

### Install npm dependencies

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Install the tool chain for building static assets.

```bash
npm ci

```

--------------------------------

### GET /api/v3/locales/{locale_id}/ response

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example response for the GET /api/v3/locales/{locale_id}/ endpoint. Shows the JSON structure of a locale object, including display_name, language_code, and meta.warnings.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "display_name": "string",
    "id": 1,
    "is_bidi": true,
    "is_default": true,
    "language_code": "string",
    "meta": {
        "type": "string",
        "warnings": [
            {
                "action": "unwrapped",
                "attribute": "string",
                "detail": "string",
                "reason": "feature_disabled",
                "tag": "string"
            },
            "string"
        ]
    }
}
```

--------------------------------

### Run tests with python manage.py test

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/project_template.html

Run the basic tests included in the home/tests.py file of a newly created project. Navigate to the project folder before running. The tests check that the root Page is automatically created, a HomePage can be created as a child of the root page, the created HomePage is renderable, and it uses the home/home_page.html template.

```text
python manage.py test

```

--------------------------------

### GET /api/v3/schema/{type_name}/ - Schemas for a content type request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request to get schemas for a content type. Requires type_name path parameter. Returns 200 OK.

```http
GET /api/v3/schema/{type_name}/ HTTP/1.1
Host: example.com

```

--------------------------------

### Create a new Wagtail project with wagtail start

Source: https://docs.wagtail.org/en/stable-8.0.x/getting_started/quick_install.html

Generates a new Wagtail project named 'mysite' in the current directory.

```bash
wagtail start mysite

```

--------------------------------

### Generate the base app with startapp

Source: https://docs.wagtail.org/en/stable-8.0.x/tutorial/create_footer_for_all_pages.html

Run this command to create a new Django app named 'base'. After running it, add 'base' to the INSTALLED_APPS list in mysite/settings/base.py.

```bash
python manage.py startapp base

```

--------------------------------

### GET /api/v3/pages/ response

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example response for the GET /api/v3/pages/ endpoint. Returns a paginated list of pages with count and items array, each containing id, title, and meta information.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "items": [
        {
            "id": 1,
            "meta": {
                "detail_url": "string",
                "first_published_at": "2026-09-28T23:19:53.425833",
                "html_url": "string",
                "locale": "string",
                "slug": "string",
                "type": "string",
                "warnings": [
                    {
                        "action": "unwrapped",
                        "attribute": "string",
                        "detail": "string",
                        "reason": "feature_disabled",
                        "tag": "string"
                    },
                    "string"
                ]
            },
            "title": "string"
        }
    ]
}
```

--------------------------------

### GET snippet detail request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Retrieve a snippet detail with GET /api/v3/snippets/{type}/{pk}/. The request includes the type and pk path parameters. No response example is shown on this page.

```http
GET /api/v3/snippets/{type}/{pk}/ HTTP/1.1
Host: example.com

```

--------------------------------

### Build and run Docker image (docker build, docker run)

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/project_template.html

Build and run the Docker image for a project created with the default template. The Dockerfile is located at /mysite/Dockerfile. Build the image with tag mysite, then run it on port 8000.

```text
docker build -t mysite .
docker run -p 8000:8000 mysite

```

--------------------------------

### Install docs dependencies and compile with make html

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Installs Sphinx and compiles the Wagtail documentation. Use the zsh alternative if your shell is zsh. The compiled documentation will be placed in docs/_build/html.

```bash
# Starting from the wagtail root directory:

# Install the documentation dependencies
pip install -e .[docs] --config-settings editable-mode=strict
# or if using zsh as your shell:
#    pip install -e '.[docs]' -U
# Compile the docs
cd docs/
make html

```

--------------------------------

### Current API user request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request to get the current API user information.

```http
GET /api/v3/whoami/ HTTP/1.1
Host: example.com

```

--------------------------------

### Configure block preview with keyword arguments

Source: https://docs.wagtail.org/en/stable-8.0.x/topics/streamfield.html

Pass preview_value, preview_template, and description when instantiating a StructBlock to enable previews in the block picker.

```python
("quote", blocks.StructBlock(
    [
        ("text", blocks.TextBlock()),
        ("source", blocks.CharBlock()),
    ],
    preview_value={"text": "This is the coolest CMS ever.", "source": "Willie Wagtail"},
    preview_template="myapp/previews/blocks/quote.html",
    description="A quote with attribution to the source, rendered as a blockquote.",
))

```

--------------------------------

### Specify Wagtail version in requirements.txt

Source: https://docs.wagtail.org/en/stable-8.0.x/releases/upgrading.html

Example line for requirements.txt to install the latest patch release of Wagtail 6.3.x.

```text
wagtail>=6.3,<6.4

```

--------------------------------

### child_of() method example

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Gets direct children of the homepage. Shows the child_of() method and an alternative using get_children().

```python
# Get a list of sections
sections = Page.objects.child_of(homepage)

# Alternative way
sections = homepage.get_children()
```

--------------------------------

### Install local Wagtail development instance (Windows)

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Install the local Wagtail development instance in your virtualenv for your Wagtail site on Windows. Replace path/to/wagtail with the path to your local Wagtail copy.

```bash
pip install -e path/to/wagtail[testing,docs] --config-settings editable-mode=strict -U

```

--------------------------------

### GET /api/v3/snippets/{type}/{pk}/ - 200 OK response

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example response for a successful GET request to the v3 API snippets endpoint. Returns a snippet object with id, meta, tags, text, and url fields.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "meta": {
        "detail_url": "string",
        "type": "string",
        "warnings": [
            {
                "action": "unwrapped",
                "attribute": "string",
                "detail": "string",
                "reason": "feature_disabled",
                "tag": "string"
            },
            "string"
        ]
    },
    "tags": [
        "string"
    ],
    "text": "string",
    "url": "string"
}
```

--------------------------------

### Auto-rebuild docs with make livehtml

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Compiles the documentation automatically on each change and serves it at localhost:4000.

```bash
# Starting from the wagtail root directory:

cd docs/
make livehtml

```

--------------------------------

### Install wagtail.contrib.redirects

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/contrib/redirects.html

Add the redirects app to INSTALLED_APPS and the RedirectMiddleware to MIDDLEWARE in your Django settings file. Run the migrate command after installing.

```python
INSTALLED_APPS = [
    # ...
    "wagtail.contrib.redirects",
]

MIDDLEWARE = [
    # ...
    # all other django middleware first
    "wagtail.contrib.redirects.middleware.RedirectMiddleware",
]

```

--------------------------------

### GET /api/v3/pages/ request

Source: https://docs.wagtail.org/en/stable-8.0.x/advanced_topics/api/v3/reference.html

Example request for the GET /api/v3/pages/ endpoint. Lists pages with optional query parameters such as type, ancestor_of, child_of, descendant_of, translation_of, locale, site, order, search, search_operator, limit, and offset.

```http
GET /api/v3/pages/ HTTP/1.1
Host: example.com
```

--------------------------------

### Install dependencies and apply migrations

Source: https://docs.wagtail.org/en/stable-8.0.x/releases/upgrading.html

Commands to install requirements, create migrations, and apply them after upgrading Wagtail.

```bash
pip install -r requirements.txt
./manage.py makemigrations
./manage.py migrate

```

--------------------------------

### Faceted search on content type

Source: https://docs.wagtail.org/en/stable-8.0.x/topics/search/searching.html

Example of using the .facet() method to get an OrderedDict of counts for a taxonomy field, here content_type_id.

```python
>>> Page.objects.search("Test").facet("content_type_id")

# Note: The keys correspond to the ID of a ContentType object; the values are the
# number of pages returned for that type
OrderedDict([
    ('2', 4),  # 4 pages have content_type_id == 2
    ('1', 2),  # 2 pages have content_type_id == 1
])
```

--------------------------------

### descendant_of() method example

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Gets EventPages that are descendants of the special_events_index page. Shows the descendant_of() method and an alternative using get_descendants().

```python
# Get EventPages that are under the special_events Page
special_events = EventPage.objects.descendant_of(special_events_index)

# Alternative way
special_events = special_events_index.get_descendants()
```

--------------------------------

### Install local Wagtail development instance (Unix)

Source: https://docs.wagtail.org/en/stable-8.0.x/contributing/developing.html

Install the local Wagtail development instance in your virtualenv for your Wagtail site on Unix-like systems. Replace path/to/wagtail with the path to your local Wagtail copy.

```bash
pip install -e path/to/wagtail"[testing,docs]" --config-settings editable-mode=strict -U

```

--------------------------------

### in_site() method example

Source: https://docs.wagtail.org/en/stable-8.0.x/reference/pages/queryset_reference.html

Gets all EventPages within the current site. Uses Site.find_for_request() to obtain the site and then in_site() to filter.

```python
# Get all the EventPages in the current site
site = Site.find_for_request(request)
site_events = EventPage.objects.in_site(site)
```
Tokens:
Raw