Documentation - Improve grammar, spelling, and punctuation

docs/topics/images.md

@@ -87,7 +87,7 @@ Reduces the height of the image to the dimension specified.
 
 ### `scale`
 
-(takes percentage)
+(takes a percentage)
 
 ```html+django
 {% image page.photo scale-50 %}
@@ -188,7 +188,7 @@ Wagtail can assign the image data to another variable using Django's `as` syntax
 The image property used for the `src` attribute is `image.url`, not `image.src`.
 ```
 
-This syntax exposes the underlying image Rendition (`tmp_photo`) to the developer. A "Rendition" contains the information specific to the way you've requested to format the image using the resize-rule, dimensions and source URL. The following properties are available:
+This syntax exposes the underlying image Rendition (`tmp_photo`) to the developer. A "Rendition" contains the information specific to the way you've requested to format the image using the resize-rule, dimensions, and source URL. The following properties are available:
 
 ### `url`
 
@@ -208,7 +208,7 @@ Alternative text for the image, typically taken from the image title.
 
 ### `attrs`
 
-A shorthand for outputting the attributes `src`, `width`, `height` and `alt` in one go:
+A shorthand for outputting the attributes `src`, `width`, `height`, and `alt` in one go:
 
 ```html+django
 <img {{ tmp_photo.attrs }} class="my-custom-class" />
@@ -311,7 +311,7 @@ Creates an image rendition using `width-500`, giving the <img> tag the CSS class
 Creates an image rendition using `width-500`, giving the <img> tag the CSS class `right`.
 
 ```{note}
-The CSS classes added to images do **not** come with any accompanying stylesheets, or inline styles. For example the `left` class will do nothing, by default. The developer is expected to add these classes to their front end CSS files, to define exactly what they want `left`, `right` or `full-width` to mean.
+The CSS classes added to images do **not** come with any accompanying stylesheets or inline styles. For example, the `left` class will do nothing, by default. The developer is expected to add these classes to their front-end CSS files, to define exactly what they want `left`, `right` or `full-width` to mean.
 ```
 
 For more information about image formats, including creating your own, see [](rich_text_image_formats).
@@ -322,7 +322,7 @@ For more information about image formats, including creating your own, see [](ri
 
 Wagtail may automatically change the format of some images when they are resized:
 
--   PNG and JPEG images don't change format
+-   PNG and JPEG images don't change the format
 -   GIF images without animation are converted to PNGs
 -   BMP images are converted to PNGs
 -   WebP images are converted to PNGs
@@ -355,7 +355,7 @@ convert images to JPEG format, the transparency will need to be replaced with a
 
 By default, Wagtail will set the background to white. But if a white background doesn't fit your design, you can specify a colour using the `bgcolor` filter.
 
-This filter takes a single argument, which is a CSS 3 or 6 digit hex code
+This filter takes a single argument, which is a CSS 3 or 6-digit hex code
 representing the colour you would like to use:
 
 ```html+django

docs/topics/pages.md

@@ -208,7 +208,7 @@ For more information, please see {meth}`wagtail.models.Page.get_url_parts`.
 
 The `Page.get_url(request)` method can be called whenever a page URL is needed. It defaults to returning local URLs (not including the protocol or domain) if it determines that the page is on the current site (via the hostname in `request`); otherwise, a full URL including the protocol and domain is returned. Whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information and facilitate the generation of local URLs.
 
-A common use case for `get_url(request)` is in any custom template tag your project may include for generating navigation menus. When writing such a custom template tag, ensure that it includes `takes_context=True` and use `context.get('request')` to safely pass the
+A common use case for `get_url(request)` is in any custom template tag your project may include for generating navigation menus. When writing such a custom template tag, ensure that it includes `takes_context=True` and uses `context.get('request')` to safely pass the
 request or `None` if no request exists in the context.
 
 For more information, please see {meth}`wagtail.models.Page.get_url`.

docs/topics/search/backends.md

@@ -31,7 +31,7 @@ WAGTAILSEARCH_BACKENDS = {
 }
 ```
 
-If you have disabled auto update, you must run the [](update_index) command on a regular basis to keep the index in sync with the database.
+If you have disabled auto-update, you must run the [](update_index) command on a regular basis to keep the index in sync with the database.
 
 (wagtailsearch_backends_atomic_rebuild)=
 
@@ -41,9 +41,9 @@ If you have disabled auto update, you must run the [](update_index) command on a
 This option may not work on Elasticsearch version 5.4.x, due to [a bug in the handling of aliases](https://github.com/elastic/elasticsearch/issues/24644) - please upgrade to 5.5 or later.
 ```
 
-By default (when using the Elasticsearch backend), when the `update_index` command is run, Wagtail deletes the index and rebuilds it from scratch. This causes the search engine to not return results until the rebuild is complete and is also risky as you can't rollback if an error occurs.
+By default (when using the Elasticsearch backend), when the `update_index` command is run, Wagtail deletes the index and rebuilds it from scratch. This causes the search engine to not return results until the rebuild is complete and is also risky as you can't roll back if an error occurs.
 
-Setting the `ATOMIC_REBUILD` setting to `True` makes Wagtail rebuild into a separate index while keep the old index active until the new one is fully built. When the rebuild is finished, the indexes are swapped atomically and the old index is deleted.
+Setting the `ATOMIC_REBUILD` setting to `True` makes Wagtail rebuild into a separate index while keeping the old index active until the new one is fully built. When the rebuild is finished, the indexes are swapped atomically and the old index is deleted.
 
 ## `BACKEND`
 
@@ -55,7 +55,7 @@ Here's a list of backends that Wagtail supports out of the box.
 
 `wagtail.search.backends.database`
 
-The database search backend searches content in the database using the full text search features of the database backend in use (such as PostgreSQL FTS, SQLite FTS5).
+The database search backend searches content in the database using the full-text search features of the database backend in use (such as PostgreSQL FTS, SQLite FTS5).
 This backend is intended to be used for development and also should be good enough to use in production on sites that don't require any Elasticsearch specific features.
 
 (wagtailsearch_backends_elasticsearch)=
@@ -101,9 +101,9 @@ WAGTAILSEARCH_BACKENDS = {
 }
 ```
 
-Other than `BACKEND`, the keys are optional and default to the values shown. Any defined key in `OPTIONS` is passed directly to the Elasticsearch constructor as case-sensitive keyword argument (for example `'max_retries': 1`).
+Other than `BACKEND`, the keys are optional and default to the values shown. Any defined key in `OPTIONS` is passed directly to the Elasticsearch constructor as a case-sensitive keyword argument (for example `'max_retries': 1`).
 
-A username and password may be optionally be supplied to the `URL` field to provide authentication credentials for the Elasticsearch service:
+A username and password may be optionally supplied to the `URL` field to provide authentication credentials for the Elasticsearch service:
 
 ```python
 WAGTAILSEARCH_BACKENDS = {
@@ -115,7 +115,7 @@ WAGTAILSEARCH_BACKENDS = {
 }
 ```
 
-`INDEX_SETTINGS` is a dictionary used to override the default settings to create the index. The default settings are defined inside the `ElasticsearchSearchBackend` class in the module `wagtail/wagtail/search/backends/elasticsearch7.py`. Any new key is added, any existing key, if not a dictionary, is replaced with the new value. Here's a sample on how to configure the number of shards and setting the Italian LanguageAnalyzer as the default analyzer:
+`INDEX_SETTINGS` is a dictionary used to override the default settings to create the index. The default settings are defined inside the `ElasticsearchSearchBackend` class in the module `wagtail/wagtail/search/backends/elasticsearch7.py`. Any new key is added and any existing key, if not a dictionary, is replaced with the new value. Here's a sample of how to configure the number of shards and set the Italian LanguageAnalyzer as the default analyzer:
 
 ```python
 WAGTAILSEARCH_BACKENDS = {
@@ -138,7 +138,7 @@ WAGTAILSEARCH_BACKENDS = {
     }
 ```
 
-If you prefer not to run an Elasticsearch server in development or production, there are many hosted services available, including [Bonsai](https://bonsai.io/), who offer a free account suitable for testing and development. To use Bonsai:
+If you prefer not to run an Elasticsearch server in development or production, there are many hosted services available, including [Bonsai](https://bonsai.io/), which offers a free account suitable for testing and development. To use Bonsai:
 
 -   Sign up for an account at `Bonsai`
 -   Use your Bonsai dashboard to create a Cluster.

docs/topics/search/indexing.md

@@ -2,9 +2,9 @@
 
 # Indexing
 
-To make a model searchable, you'll need to add it into the search index. All pages, images and documents are indexed for you, so you can start searching them right away.
+To make a model searchable, you'll need to add it to the search index. All pages, images, and documents are indexed for you, so you can start searching them right away.
 
-If you have created some extra fields in a subclass of Page or Image, you may want to add these new fields to the search index too so that a user's search query will match on their content. See {ref}`wagtailsearch_indexing_fields` for info on how to do this.
+If you have created some extra fields in a subclass of Page or Image, you may want to add these new fields to the search index too so that a user's search query will match their content. See {ref}`wagtailsearch_indexing_fields` for info on how to do this.
 
 If you have a custom model that you would like to make searchable, see {ref}`wagtailsearch_indexing_models`.
 
@@ -12,7 +12,7 @@ If you have a custom model that you would like to make searchable, see {ref}`wag
 
 ## Updating the index
 
-If the search index is kept separate from the database (when using Elasticsearch for example), you need to keep them both in sync. There are two ways to do this: using the search signal handlers, or calling the `update_index` command periodically. For best speed and reliability, it's best to use both if possible.
+If the search index is kept separate from the database (when using Elasticsearch for example), you need to keep them both in sync. There are two ways to do this: using the search signal handlers, or calling the `update_index` command periodically. For the best speed and reliability, it's best to use both if possible.
 
 ### Signal handlers
 
@@ -20,11 +20,11 @@ If the search index is kept separate from the database (when using Elasticsearch
 
 In some cases, you may not want your content to be automatically reindexed and instead rely on the `update_index` command for indexing. If you need to disable these signal handlers, use one of the following methods:
 
-#### Disabling auto update signal handlers for a model
+#### Disabling auto-update signal handlers for a model
 
 You can disable the signal handlers for an individual model by adding `search_auto_update = False` as an attribute on the model class.
 
-#### Disabling auto update signal handlers for a search backend/whole site
+#### Disabling auto-update signal handlers for a search backend/whole site
 
 You can disable the signal handlers for a whole search backend by setting the `AUTO_UPDATE` setting on the backend to `False`.
 
@@ -89,12 +89,12 @@ These are used for performing full-text searches on your models, usually for tex
 -   **boost** (`int/float`) - This allows you to set fields as being more important than others. Setting this to a high number on a field will cause pages with matches in that field to be ranked higher. By default, this is set to 2 on the Page title field and 1 on all other fields.
 
     ```{note}
-    The PostgresSQL full text search only supports [four weight levels (A, B, C, D)](https://www.postgresql.org/docs/current/textsearch-features.html).
+    The PostgresSQL full-text search only supports [four weight levels (A, B, C, D)](https://www.postgresql.org/docs/current/textsearch-features.html).
     When the database search backend `wagtail.search.backends.database` is used on a PostgreSQL database, it will take all boost values in the project into consideration and group them into the four available weights.
 
     This means that in this configuration there are effectively only four boost levels used for ranking the search results, even if more boost values have been used.
 
-    You can find out roughly which boost thresholds map to which weight in PostgresSQL by starting an new Django shell with `./manage.py shell` and inspecting `wagtail.search.backends.database.postgres.weights.BOOST_WEIGHTS`.
+    You can find out roughly which boost thresholds map to which weight in PostgreSQL by starting a new Django shell with `./manage.py shell` and inspecting `wagtail.search.backends.database.postgres.weights.BOOST_WEIGHTS`.
     You should see something like `[(10.0, 'A'), (7.166666666666666, 'B'), (4.333333333333333, 'C'), (1.5, 'D')]`.
     Boost values above each threshold will be treated with the respective weight.
     ```
@@ -105,12 +105,12 @@ These are used for performing full-text searches on your models, usually for tex
 
 ### `index.AutocompleteField`
 
-These are used for autocomplete queries which match partial words. For example, a page titled `Hello World!` will be found if the user only types `Hel` into the search box.
+These are used for autocomplete queries that match partial words. For example, a page titled `Hello World!` will be found if the user only types `Hel` into the search box.
 
 This takes the exact same options as `index.SearchField` (with the exception of `partial_match`, which has no effect).
 
 ```{note}
-Only index fields that are displayed in the search results with ``index.AutocompleteField``. This allows users to see any words that were partial-matched on.
+`index.AutocompleteField` should only be used on fields that are displayed in the search results. This allows users to see any words that were partial-matched.
 ```
 
 ### `index.FilterField`

docs/topics/search/searching.md

@@ -106,7 +106,7 @@ field (such as category or page type).
 
 The `.facet(field_name)` method returns an `OrderedDict`. The keys are
 the IDs of the related objects that have been referenced by the specified field, and the
-values are the number of references found for each ID. The results are ordered by number
+values are the number of references found for each ID. The results are ordered by the number
 of references descending.
 
 For example, to find the most common page types in the search results:
@@ -126,12 +126,12 @@ OrderedDict([
 
 ### Search operator
 
-The search operator specifies how search should behave when the user has typed in multiple search terms. There are two possible values:
+The search operator specifies how the search should behave when the user has typed in multiple search terms. There are two possible values:
 
 -   "or" - The results must match at least one term (default for Elasticsearch)
 -   "and" - The results must match all terms (default for database search)
 
-Both operators have benefits and drawbacks. The "or" operator will return many more results but will likely contain a lot of results that aren't relevant. The "and" operator only returns results that contain all search terms, but require the user to be more precise with their query.
+Both operators have benefits and drawbacks. The "or" operator will return many more results but will likely contain a lot of results that aren't relevant. The "and" operator only returns results that contain all search terms, but requires the user to be more precise with their query.
 
 We recommend using the "or" operator when ordering by relevance and the "and" operator when ordering by anything else (note: the database backend doesn't currently support ordering by relevance).
 
@@ -171,7 +171,7 @@ For page, image and document models, the `operator` keyword argument is also sup
 
 ### Phrase searching
 
-Phrase searching is used for finding whole sentence or phrase rather than individual terms.
+Phrase searching is used for finding whole sentences or phrases rather than individual terms.
 The terms must appear together and in the same order.
 
 For example:
@@ -237,7 +237,7 @@ For example:
 
 `Phrase(query_string)`
 
-This class wraps a string containing a phrase. See previous section for how this works.
+This class wraps a string containing a phrase. See the previous section for how this works.
 
 For example:
 

docs/topics/snippets.md

@@ -59,7 +59,7 @@ def adverts(context):
     }
 ```
 
-`@register.inclusion_tag()` takes two variables: a template and a boolean on whether that template should be passed a request context. It's a good idea to include request contexts in your custom template tags, since some Wagtail-specific template tags like `pageurl` need the context to work properly. The template tag function could take arguments and filter the adverts to return a specific instance of the model, but for brevity we'll just use `Advert.objects.all()`.
+`@register.inclusion_tag()` takes two variables: a template and a boolean on whether that template should be passed a request context. It's a good idea to include request contexts in your custom template tags, since some Wagtail-specific template tags like `pageurl` need the context to work properly. The template tag function could take arguments and filter the adverts to return a specific instance of the model, but for brevity, we'll just use `Advert.objects.all()`.
 
 Here's what's in the template used by this template tag:
 
@@ -112,7 +112,7 @@ In the above example, the list of adverts is a fixed list that is displayed via
 
 The snippet could then be accessed within your template as `page.advert`.
 
-To attach multiple adverts to a page, the `FieldPanel` can be placed on an inline child object of `BookPage` rather than on `BookPage` itself. Here, this child model is named `BookPageAdvertPlacement` (so called because there is one such object for each time that an advert is placed on a BookPage):
+To attach multiple adverts to a page, the `FieldPanel` can be placed on an inline child object of `BookPage` rather than on `BookPage` itself. Here, this child model is named `BookPageAdvertPlacement` (so-called because there is one such object for each time that an advert is placed on a BookPage):
 
 ```python
 from django.db import models
@@ -327,7 +327,7 @@ The `DraftStateMixin` class was introduced.
 Support for scheduled publishing via `PublishingPanel` was introduced.
 ```
 
-If a snippet model inherits from {class}`~wagtail.models.DraftStateMixin`, Wagtail will automatically add a live/draft status column to the listing view, change the "Save" action menu to "Save draft", and add a new "Publish" action menu in the editor. Any changes you save in the snippets admin will be saved as revisions and will not be reflected to the "live" snippet instance until you publish the changes.
+If a snippet model inherits from {class}`~wagtail.models.DraftStateMixin`, Wagtail will automatically add a live/draft status column to the listing view, change the "Save" action menu to "Save draft", and add a new "Publish" action menu in the editor. Any changes you save in the snippets admin will be saved as revisions and will not be reflected in the "live" snippet instance until you publish the changes.
 
 Wagtail will also allow you to set publishing schedules for instances of the model if there is a `PublishingPanel` in the model's panels definition.
 

docs/topics/streamfield.md

@@ -302,7 +302,7 @@ When reading back the content of a StreamField, the value of a StreamBlock is a
 
 ### Limiting block counts
 
-By default, a StreamField can contain an unlimited number of blocks. The `min_num` and `max_num` options on `StreamField` or `StreamBlock` allow you to set a minimum or maximum number of blocks:
+By default, a StreamField can contain an unlimited number of blocks. The `min_num` and `max_num` options on `StreamField` or `StreamBlock` allow you to set a minimum or a maximum number of blocks:
 
 ```python
 body = StreamField([
@@ -325,7 +325,7 @@ class CommonContentBlock(blocks.StreamBlock):
         max_num = 5
 ```
 
-The `block_counts` option can be used to set a minimum or maximum count for specific block types. This accepts a dict, mapping block names to a dict containing either or both of `min_num` and `max_num`. For example, to permit between 1 and 3 'heading' blocks:
+The `block_counts` option can be used to set a minimum or maximum count for specific block types. This accepts a dict, mapping block names to a dict containing either or both `min_num` and `max_num`. For example, to permit between 1 and 3 'heading' blocks:
 
 ```python
 body = StreamField([
@@ -396,7 +396,7 @@ Within the template, the block value is accessible as the variable `value`:
 </div>
 ```
 
-Since `first_name`, `surname`, `photo` and `biography` are defined as blocks in their own right, this could also be written as:
+Since `first_name`, `surname`, `photo`, and `biography` are defined as blocks in their own right, this could also be written as:
 
 ```html+django
 {% load wagtailcore_tags wagtailimages_tags %}
@@ -502,7 +502,7 @@ All block types implement a common API for rendering their front-end and form re
 
 ## Modifying StreamField data
 
-A StreamField's value behaves as a list, and blocks can be inserted, overwritten and deleted before saving the instance back to the database. A new item can be written to the list as a tuple of _(block_type, value)_ - when read back, it will be returned as a `BoundBlock` object.
+A StreamField's value behaves as a list, and blocks can be inserted, overwritten, and deleted before saving the instance back to the database. A new item can be written to the list as a tuple of _(block_type, value)_ - when read back, it will be returned as a `BoundBlock` object.
 
 ```python
 # Replace the first block with a new block of type 'heading'

docs/topics/writing_templates.md

@@ -37,7 +37,7 @@ The data/content entered into each page is accessed/output through Django's `{{
 
 A custom variable name can be configured on the page model {attr}`wagtail.models.Page.context_object_name`. If a custom name is defined, `page` is still available for use in shared templates.
 
-Additionally `request.` is available and contains Django's request object.
+Additionally, `request.` is available and contains Django's request object.
 
 ## Static assets
 
@@ -62,7 +62,7 @@ Any file within the static folder should be inserted into your HTML using the `{
 
 Images uploaded to a Wagtail site by its users (as opposed to a developer's static files, mentioned above) go into the image library and from there are added to pages via the [page editor interface](inserting_images).
 
-Unlike other CMSs, adding images to a page does not involve choosing a "version" of the image to use. Wagtail has no predefined image "formats" or "sizes". Instead the template developer defines image manipulation to occur _on the fly_ when the image is requested, via a special syntax within the template.
+Unlike other CMSs, adding images to a page does not involve choosing a "version" of the image to use. Wagtail has no predefined image "formats" or "sizes". Instead, the template developer defines image manipulation to occur _on the fly_ when the image is requested, via a special syntax within the template.
 
 Images from the library must be requested using this syntax, but a developer's static images can be added via conventional means like `img` tags. Only images from the library can be manipulated on the fly.
 
@@ -102,7 +102,7 @@ See [](image_tag) for full documentation.
 
 ## Rich text (filter)
 
-This filter takes a chunk of HTML content and renders it as safe HTML in the page. Importantly, it also expands internal shorthand references to embedded images, and links made in the Wagtail editor, into fully-baked HTML ready for display.
+This filter takes a chunk of HTML content and renders it as safe HTML in the page. Importantly, it also expands internal shorthand references to embedded images and links made in the Wagtail editor, into fully-baked HTML ready for display.
 
 Only fields using `RichTextField` need this applied in the template.
 
@@ -191,7 +191,7 @@ Like `pageurl`, this will try to provide a relative link if possible, but will d
 
 ## Static files (tag)
 
-Used to load anything from your static files directory. Use of this tag avoids rewriting all static paths if hosting arrangements change, as they might between development and live environments.
+Used to load anything from your static files directory. Use of this tag avoids rewriting all static paths if hosting arrangements change, such as when moving from development to a live environment.
 
 ```html+django
 {% load static %}
@@ -240,7 +240,7 @@ We recommend putting the tag near the top of the `<body>` element to allow keybo
 </body>
 ```
 
-By default the User Bar appears in the bottom right of the browser window, inset from the edge. If this conflicts with your design it can be moved by passing a parameter to the template tag. These examples show you how to position the userbar in each corner of the screen:
+By default, the User Bar appears in the bottom right of the browser window, inset from the edge. If this conflicts with your design it can be moved by passing a parameter to the template tag. These examples show you how to position the userbar in each corner of the screen:
 
 ```html+django
 ...
@@ -262,7 +262,7 @@ The userbar can be positioned where it works best with your design. Alternativel
 
 ## Varying output between preview and live
 
-Sometimes you may wish to vary the template output depending on whether the page is being previewed or viewed live. For example, if you have visitor tracking code such as Google Analytics in place on your site, it's a good idea to leave this out when previewing, so that editor activity doesn't appear in your analytics reports. Wagtail provides a `request.is_preview` variable to distinguish between preview and live:
+Sometimes you may wish to vary the template output depending on whether the page is being previewed or viewed live. For example, if you have visitor-tracking code such as Google Analytics in place on your site, it's a good idea to leave this out when previewing, so that editor activity doesn't appear in your analytics reports. Wagtail provides a `request.is_preview` variable to distinguish between preview and live:
 
 ```html+django
 {% if not request.is_preview %}