documentation - markdown formatting

- apply general fixes to existing markdown documentation
- various cases of rst syntax still used
- update some links to be the new format
- clean up line breaks (prettier)

docs/advanced_topics/api/v2/usage.md

@@ -337,6 +337,7 @@ to only include descendants of that page (children, grandchildren etc.).
 ### Filtering pages by site
 
 ```{versionadded} 4.0
+
 ```
 
 By default, the API will look for the site based on the hostname of the request.

docs/advanced_topics/images/renditions.md

@@ -46,7 +46,7 @@ The `prefetch_renditions` method is only applicable in Wagtail versions 4.0 and
 
 ### Image QuerySets
 
-When working with an Image QuerySet, you can make use of Wagtail's built-in ``prefetch_renditions`` queryset method to prefetch the renditions needed.
+When working with an Image QuerySet, you can make use of Wagtail's built-in `prefetch_renditions` queryset method to prefetch the renditions needed.
 
 For example, say you were rendering a list of all the images uploaded by a certain user:
 
@@ -64,7 +64,7 @@ def get_images_uploaded_by_user(user)::
 
 The above will prefetch all renditions even if we may not need them.
 
-If images in your project tend to have very large numbers of renditions, and you know in advance the ones you need, you might want to consider specifying a set of filters to the ``prefetch_renditions`` method and only select the renditions you need for rendering. For example:
+If images in your project tend to have very large numbers of renditions, and you know in advance the ones you need, you might want to consider specifying a set of filters to the `prefetch_renditions` method and only select the renditions you need for rendering. For example:
 
 ```python
 def get_images_uploaded_by_user(user):
@@ -92,7 +92,6 @@ def get_events():
     return EventPage.objects.live().select_related("listing_image").prefetch_related("listing_image__renditions")
 ```
 
-
 If you know in advance the renditions you'll need, you can filter the renditions queryset to use:
 
 ```python
@@ -103,7 +102,7 @@ from wagtail.images import get_image_model
 def get_events():
     Image = get_image_model()
     filters = ["fill-300x186", "fill-600x400", "fill-940x680"]
-    
+
     # `Prefetch` is used to fetch only the required renditions
     prefetch_images_and_renditions = Prefetch(
         "listing_image",

docs/contributing/developing.md

@@ -14,7 +14,7 @@ If you'd prefer to set up all the components manually, read on. These instructio
 
 ## Setting up the Wagtail codebase
 
-The preferred way to install the correct version of Node is to use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) or [Fast Node Manager (fnm)](https://github.com/Schniz/fnm), which will always align the version with the supplied  `.nvmrc` file in the root of the project. To ensure you are running the correct version of Node, run `nvm install` or `fnm install` from the project root.
+The preferred way to install the correct version of Node is to use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) or [Fast Node Manager (fnm)](https://github.com/Schniz/fnm), which will always align the version with the supplied `.nvmrc` file in the root of the project. To ensure you are running the correct version of Node, run `nvm install` or `fnm install` from the project root.
 Alternatively, you can install [Node.js](https://nodejs.org/) directly, ensure you install the version as declared in the project's root `.nvmrc` file.
 
 You will also need to install the **libjpeg** and **zlib** libraries, if you haven't done so already - see Pillow's [platform-specific installation instructions](https://pillow.readthedocs.org/en/latest/installation.html#external-libraries).
@@ -44,7 +44,7 @@ Compile the assets:
 $ npm run build
 ```
 
-Any Wagtail sites you start up in this virtualenv will now run against this development instance of Wagtail.  We recommend using the [Wagtail Bakery demo site](https://github.com/wagtail/bakerydemo/) as a basis for developing Wagtail. Keep in mind that the setup steps for a Wagtail site may include installing a release version of Wagtail, which will override the development version you've just set up. In this case, you should install the site before running the `pip install -e` step, or re-run that step after the site is installed.
+Any Wagtail sites you start up in this virtualenv will now run against this development instance of Wagtail. We recommend using the [Wagtail Bakery demo site](https://github.com/wagtail/bakerydemo/) as a basis for developing Wagtail. Keep in mind that the setup steps for a Wagtail site may include installing a release version of Wagtail, which will override the development version you've just set up. In this case, you should install the site before running the `pip install -e` step, or re-run that step after the site is installed.
 
 (testing)=
 
@@ -125,12 +125,12 @@ the tests against it.
 
 If you need to use different connection settings, use the following environment variables which correspond to the respective keys within Django's [DATABASES](https://docs.djangoproject.com/en/stable/ref/settings/#databases) settings dictionary:
 
-- `DATABASE_ENGINE`
-- `DATABASE_NAME`
-- `DATABASE_PASSWORD`
-- `DATABASE_HOST`
-    - Note that for MySQL, this must be `127.0.0.1` rather than `localhost` if you need to connect using a TCP socket
-- `DATABASE_PORT`
+-   `DATABASE_ENGINE`
+-   `DATABASE_NAME`
+-   `DATABASE_PASSWORD`
+-   `DATABASE_HOST`
+    -   Note that for MySQL, this must be `127.0.0.1` rather than `localhost` if you need to connect using a TCP socket
+-   `DATABASE_PORT`
 
 It is also possible to set `DATABASE_DRIVER`, which corresponds to the `driver` value within `OPTIONS` if an SQL Server engine is used.
 
@@ -198,10 +198,10 @@ We aim for Wagtail to work in those environments, there are known support gaps f
 
 IE 11 support has been officially dropped in 2.15 as it is gradually falling out of use. Features already known not to work include:
 
-- Rich text copy-paste in the rich text editor.
-- Sticky toolbar in the rich text editor.
-- Focus outline styles in the main menu & explorer menu.
-- Keyboard access to the actions in page listing tables.
+-   Rich text copy-paste in the rich text editor.
+-   Sticky toolbar in the rich text editor.
+-   Focus outline styles in the main menu & explorer menu.
+-   Keyboard access to the actions in page listing tables.
 
 **Unsupported browsers / devices include:**
 
@@ -215,26 +215,26 @@ IE 11 support has been officially dropped in 2.15 as it is gradually falling out
 
 We want to make Wagtail accessible for users of a wide variety of assistive technologies. The specific standard we aim for is [WCAG2.1](https://www.w3.org/TR/WCAG21/), AA level. Here are specific assistive technologies we aim to test for, and ultimately support:
 
-- [NVDA](https://www.nvaccess.org/download/) on Windows with Firefox ESR
-- [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web) on macOS with Safari
-- [Windows Magnifier](https://support.microsoft.com/en-gb/help/11542/windows-use-magnifier) and macOS Zoom
-- Windows Speech Recognition and macOS Dictation
-- Mobile [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web) on iOS, or [TalkBack](https://support.google.com/accessibility/android/answer/6283677?hl=en-GB) on Android
-- Windows [High-contrast mode](https://support.microsoft.com/en-us/windows/use-high-contrast-mode-in-windows-10-fedc744c-90ac-69df-aed5-c8a90125e696)
+-   [NVDA](https://www.nvaccess.org/download/) on Windows with Firefox ESR
+-   [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web) on macOS with Safari
+-   [Windows Magnifier](https://support.microsoft.com/en-gb/help/11542/windows-use-magnifier) and macOS Zoom
+-   Windows Speech Recognition and macOS Dictation
+-   Mobile [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web) on iOS, or [TalkBack](https://support.google.com/accessibility/android/answer/6283677?hl=en-GB) on Android
+-   Windows [High-contrast mode](https://support.microsoft.com/en-us/windows/use-high-contrast-mode-in-windows-10-fedc744c-90ac-69df-aed5-c8a90125e696)
 
 We aim for Wagtail to work in those environments. Our development standards ensure that the site is usable with other assistive technologies. In practice, testing with assistive technology can be a daunting task that requires specialised training – here are tools we rely on to help identify accessibility issues, to use during development and code reviews:
 
-- [react-axe](https://github.com/dequelabs/react-axe) integrated directly in our build tools, to identify actionable issues. Logs its results in the browser console.
-- [@wordpress/jest-puppeteer-axe](https://github.com/WordPress/gutenberg/tree/trunk/packages/jest-puppeteer-axe) running Axe checks as part of integration tests.
-- [Axe](https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd) Chrome extension for more comprehensive automated tests of a given page.
-- [Accessibility Insights for Web](https://accessibilityinsights.io/docs/en/web/overview) Chrome extension for semi-automated tests, and manual audits.
+-   [react-axe](https://github.com/dequelabs/react-axe) integrated directly in our build tools, to identify actionable issues. Logs its results in the browser console.
+-   [@wordpress/jest-puppeteer-axe](https://github.com/WordPress/gutenberg/tree/trunk/packages/jest-puppeteer-axe) running Axe checks as part of integration tests.
+-   [Axe](https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd) Chrome extension for more comprehensive automated tests of a given page.
+-   [Accessibility Insights for Web](https://accessibilityinsights.io/docs/en/web/overview) Chrome extension for semi-automated tests, and manual audits.
 
 ### Known accessibility issues
 
 Wagtail’s administration interface isn’t fully accessible at the moment. We actively work on fixing issues both as part of ongoing maintenance and bigger overhauls. To learn about known issues, check out:
 
-- The [WCAG2.1 AA for CMS admin](https://github.com/wagtail/wagtail/projects/5) issues backlog.
-- Our [2021 accessibility audit](https://docs.google.com/spreadsheets/d/1l7tnpEyJiC5BWE_JX0XCkknyrjxYA5T2aee5JgPnmi4/edit).
+-   The [WCAG2.1 AA for CMS admin](https://github.com/wagtail/wagtail/projects/5) issues backlog.
+-   Our [2021 accessibility audit](https://docs.google.com/spreadsheets/d/1l7tnpEyJiC5BWE_JX0XCkknyrjxYA5T2aee5JgPnmi4/edit).
 
 The audit also states which parts of Wagtail have and haven’t been tested, how issues affect WCAG 2.1 compliance, and the likely impact on users.
 

docs/contributing/issue_tracking.md

@@ -14,15 +14,15 @@ Don't be discouraged if you feel that your ticket has been given a lower priorit
 
 The possible milestones that it might be assigned to are as follows:
 
-* **invalid** (closed): this issue doesn't identify a specific action to be taken, or the action is not one that we want to take. For example - a bug report for something that's working as designed, or a feature request for something that's actively harmful.
-* **real-soon-now**: no-one on the core team has resources allocated to work on this right now, but we know it's a pain point, and it will be prioritised whenever we next get a chance to choose something new to work on. In practice, that kind of free choice doesn't happen very often - there are lots of pressures determining what we work on from day to day - so if this is a feature or fix you need, we encourage you to work on it and contribute a pull request, rather than waiting for the core team to get round to it!
-* A specific version number (eg. **1.6**): the issue is important enough that it needs to be fixed in this version. There are resources allocated and/or plans to work on the issue in the given version.
-* No milestone: the issue is accepted as valid once the `status:Unconfirmed` label is removed (i.e. it's a bug report for a legitimate bug, or a useful feature request) but is not deemed a priority to work on (in the opinion of the core team). For example - a bug that's only cosmetic, or a feature that would be kind of neat but not really essential. There are no resources allocated to it - feel free to take it on!
+-   **invalid** (closed): this issue doesn't identify a specific action to be taken, or the action is not one that we want to take. For example - a bug report for something that's working as designed, or a feature request for something that's actively harmful.
+-   **real-soon-now**: no-one on the core team has resources allocated to work on this right now, but we know it's a pain point, and it will be prioritised whenever we next get a chance to choose something new to work on. In practice, that kind of free choice doesn't happen very often - there are lots of pressures determining what we work on from day to day - so if this is a feature or fix you need, we encourage you to work on it and contribute a pull request, rather than waiting for the core team to get round to it!
+-   A specific version number (eg. **1.6**): the issue is important enough that it needs to be fixed in this version. There are resources allocated and/or plans to work on the issue in the given version.
+-   No milestone: the issue is accepted as valid once the `status:Unconfirmed` label is removed (i.e. it's a bug report for a legitimate bug, or a useful feature request) but is not deemed a priority to work on (in the opinion of the core team). For example - a bug that's only cosmetic, or a feature that would be kind of neat but not really essential. There are no resources allocated to it - feel free to take it on!
 
 On some occasions it may take longer for the core team to classify an issue into a milestone. For example:
 
-* It may require a non-trivial amount of work to confirm the presence of a bug. In this case, feedback and further details from other contributors, whether or not they can replicate the bug, would be particularly welcomed.
-* It may require further discussion to decide whether the proposal is a good idea or not - if so, it will be tagged ["design decision needed"](https://github.com/wagtail/wagtail/labels/status%3ANeeds%20Design%20Decision).
+-   It may require a non-trivial amount of work to confirm the presence of a bug. In this case, feedback and further details from other contributors, whether or not they can replicate the bug, would be particularly welcomed.
+-   It may require further discussion to decide whether the proposal is a good idea or not - if so, it will be tagged ["design decision needed"](https://github.com/wagtail/wagtail/labels/status%3ANeeds%20Design%20Decision).
 
 We will endeavour to make sure that issues don't remain in this state for prolonged periods. Issues and PRs tagged "design decision needed" will be revisited regularly and discussed with at least two core contributors - we aim to review each ticket at least once per release cycle (= 6 weeks) as part of weekly core team meetings.
 
@@ -30,9 +30,9 @@ We will endeavour to make sure that issues don't remain in this state for prolon
 
 As with issues, the core team will classify pull requests as soon as they are opened, usually within one day. Unless the change is invalid or particularly contentious (in which case it will be closed or marked as "design decision needed"). It will generally be classified under the next applicable version - the next minor release for new features, or the next patch release for bugfixes - and marked as 'Needs review'.
 
-* All contributors, core and non-core, are invited to offer feedback on the pull request.
-* Core team members are invited to assign themselves to the pull request for review.
-* More specific details on how to triage Pull Requests can be found on the [PR triage wiki page](https://github.com/wagtail/wagtail/wiki/PR-triage).
+-   All contributors, core and non-core, are invited to offer feedback on the pull request.
+-   Core team members are invited to assign themselves to the pull request for review.
+-   More specific details on how to triage Pull Requests can be found on the [PR triage wiki page](https://github.com/wagtail/wagtail/wiki/PR-triage).
 
 Subsequently (ideally within a week or two, but possibly longer for larger submissions) a core team member will merge it if it is ready to be merged, or tag it as requiring further work ('needs work' / 'needs tests' / 'needs docs'). Pull requests that require further work are handled and prioritised in the same way as issues - anyone is welcome to pick one up from the backlog, whether or not they were the original committer.
 
@@ -44,5 +44,5 @@ Core team members working on Wagtail are expected to go through the same process
 
 We aim to release a new version every 2 months. To keep to this schedule, we will tend to 'bump' issues and PRs to a future release where necessary, rather than let them delay the present one. For this reason, an issue being tagged under a particular release milestone should not be taken as any kind of guarantee that the feature will actually be shipped in that release.
 
-* See the [Release Schedule wiki page](https://github.com/wagtail/wagtail/wiki/Release-schedule) for a full list of dates.
-* See the [Roadmap wiki page](https://github.com/wagtail/wagtail/wiki/Roadmap) for a general guide of project planning.
+-   See the [Release Schedule wiki page](https://github.com/wagtail/wagtail/wiki/Release-schedule) for a full list of dates.
+-   See the [Roadmap wiki page](https://github.com/wagtail/wagtail/wiki/Roadmap) for a general guide of project planning.

docs/contributing/security.md

@@ -19,11 +19,11 @@ Django security issues should be reported directly to the Django Project, follow
 
 At any given time, the Wagtail team provides official security support for several versions of Wagtail:
 
-- The ``main`` development branch, hosted on GitHub, which will become the next release of Wagtail, receives security support.
-- The two most recent Wagtail release series receive security support.
-  For example, during the development cycle leading to the release of
-  Wagtail 2.6, support will be provided for Wagtail 2.5 and Wagtail 2.4. Upon the release of Wagtail 2.6, Wagtail 2.4's security support will end.
-- The latest long-term support release will receive security updates.
+-   The `main` development branch, hosted on GitHub, which will become the next release of Wagtail, receives security support.
+-   The two most recent Wagtail release series receive security support.
+    For example, during the development cycle leading to the release of
+    Wagtail 2.6, support will be provided for Wagtail 2.5 and Wagtail 2.4. Upon the release of Wagtail 2.6, Wagtail 2.4's security support will end.
+-   The latest long-term support release will receive security updates.
 
 When new releases are issued for security reasons, the accompanying notice will include a list of affected versions.
 This list is comprised solely of supported versions of Wagtail: older versions may also be affected, but we do not investigate to determine that, and will not issue patches or new releases for those versions.

docs/contributing/ui_guidelines.md

@@ -2,17 +2,17 @@
 
 Wagtail’s user interface is built with:
 
-- **HTML** using [Django templates](https://docs.djangoproject.com/en/stable/ref/templates/language/)
-- **CSS** using [Sass](https://sass-lang.com/) and [Tailwind](https://tailwindcss.com/)
-- **JavaScript** with [TypeScript](https://www.typescriptlang.org/)
-- **SVG** for our icons, minified with [SVGO](https://jakearchibald.github.io/svgomg/)
+-   **HTML** using [Django templates](https://docs.djangoproject.com/en/stable/ref/templates/language/)
+-   **CSS** using [Sass](https://sass-lang.com/) and [Tailwind](https://tailwindcss.com/)
+-   **JavaScript** with [TypeScript](https://www.typescriptlang.org/)
+-   **SVG** for our icons, minified with [SVGO](https://jakearchibald.github.io/svgomg/)
 
 ## Linting and formatting
 
 Here are the available commands:
 
-- `make lint` will run all linting, `make lint-server` lints templates, `make lint-client` lints JS/CSS.
-- `make format` will run all formatting and fixing of linting issues. There is also `make format-server` and `make format-client`.
+-   `make lint` will run all linting, `make lint-server` lints templates, `make lint-client` lints JS/CSS.
+-   `make format` will run all formatting and fixing of linting issues. There is also `make format-server` and `make format-client`.
 
 Have a look at our `Makefile` tasks and `package.json` scripts if you prefer more granular options.
 
@@ -20,30 +20,30 @@ Have a look at our `Makefile` tasks and `package.json` scripts if you prefer mor
 
 We use [djhtml](https://github.com/rtts/djhtml) for formatting and [Curlylint](https://www.curlylint.org/) for linting.
 
-- Write [valid](https://validator.w3.org/nu/), [semantic](https://html5doctor.com/element-index/) HTML.
-- Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_bad_aria).
-- Use classes for styling, `data-` attributes for JavaScript behaviour, IDs for semantics only.
-- For comments, use [Django template syntax](https://docs.djangoproject.com/en/stable/ref/templates/language/#comments) instead of HTML.
+-   Write [valid](https://validator.w3.org/nu/), [semantic](https://html5doctor.com/element-index/) HTML.
+-   Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_bad_aria).
+-   Use classes for styling, `data-` attributes for JavaScript behaviour, IDs for semantics only.
+-   For comments, use [Django template syntax](https://docs.djangoproject.com/en/stable/ref/templates/language/#comments) instead of HTML.
 
 ## CSS guidelines
 
 We use [Prettier](https://prettier.io/) for formatting and [Stylelint](https://stylelint.io/) for linting.
 
-- We follow [BEM](http://getbem.com/) and [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/), with a large amount of utilities created with [Tailwind](https://tailwindcss.com/).
-- Familiarise yourself with our [stylelint-config-wagtail](https://github.com/wagtail/stylelint-config-wagtail) configuration, which details our preferred code style.
-- Use `rems` for `font-size`, because they offer absolute control over text. Additionally, unit-less `line-height` is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the `font-size`.
-- Always use variables for design tokens such as colours or font sizes, rather than hard-coding specific values.
-- We use the `w-` prefix for all styles intended to be reusable by Wagtail site implementers.
+-   We follow [BEM](http://getbem.com/) and [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/), with a large amount of utilities created with [Tailwind](https://tailwindcss.com/).
+-   Familiarise yourself with our [stylelint-config-wagtail](https://github.com/wagtail/stylelint-config-wagtail) configuration, which details our preferred code style.
+-   Use `rems` for `font-size`, because they offer absolute control over text. Additionally, unit-less `line-height` is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the `font-size`.
+-   Always use variables for design tokens such as colours or font sizes, rather than hard-coding specific values.
+-   We use the `w-` prefix for all styles intended to be reusable by Wagtail site implementers.
 
 ## JavaScript guidelines
 
 We use [Prettier](https://prettier.io/) for formatting and [ESLint](https://eslint.org/) for linting.
 
-- We follow a somewhat relaxed version of the [Airbnb styleguide](https://github.com/airbnb/javascript).
-- Familiarise yourself with our [eslint-config-wagtail](https://github.com/wagtail/eslint-config-wagtail) configuration, which details our preferred code style.
+-   We follow a somewhat relaxed version of the [Airbnb styleguide](https://github.com/airbnb/javascript).
+-   Familiarise yourself with our [eslint-config-wagtail](https://github.com/wagtail/eslint-config-wagtail) configuration, which details our preferred code style.
 
 ## Multilingual support
 
 This is an area of active improvement for Wagtail, with [ongoing discussions](https://github.com/wagtail/wagtail/discussions/8017).
 
-- Always use the `trimmed` attribute on `blocktrans` tags to prevent unnecessary whitespace from being added to the translation strings.
+-   Always use the `trimmed` attribute on `blocktrans` tags to prevent unnecessary whitespace from being added to the translation strings.

docs/getting_started/index.md

@@ -53,8 +53,8 @@ If you\'d like to add Wagtail to an existing Django project instead, see [Integr
 
 There are a few optional packages which are not installed by default but are recommended to improve performance or add features to Wagtail, including:
 
-- [Elasticsearch](/advanced_topics/performance).
-- [Feature Detection](image_feature_detection).
+-   [Elasticsearch](/advanced_topics/performance).
+-   [Feature Detection](image_feature_detection).
 
 ```{toctree}
 ---

docs/getting_started/the_zen_of_wagtail.md

@@ -30,4 +30,4 @@ A common sight in content management systems is a point-and-click interface to l
 
 It looks nice in the sales pitch, but in reality, no CMS end-user can realistically make that kind of fundamental change - on a live site, no less - unless they have a programmer's insight into how the site is built, and what impact the change will have. As such, it will always be the programmer's job to negotiate that point-and-click interface - all you've done is taken them away from the comfortable world of writing code, where they have a whole ecosystem of tools, from text editors to version control systems, to help them develop, test and deploy their code changes.
 
-Wagtail recognises that most programming tasks are best done by writing code, and does not try to turn them into box-filling exercises when there's no good reason to. Likewise, when building functionality for your site, you should keep in mind that some features are destined to be maintained by the programmer rather than a content editor, and consider whether making them configurable through the Wagtail admin is going to be more of a hindrance than a convenience. For example, Wagtail provides a form builder to allow content authors to create general-purpose data collection forms. You might be tempted to use this as the basis for more complex forms that integrate with (for example) a CRM system or payment processor - however, in this case there's no way to edit the form fields without rewriting the backend logic, so making them editable through Wagtail has limited value. More likely, you'd be better off building these using Django's form framework, where the form fields are defined entirely in code.
+Wagtail recognises that most programming tasks are best done by writing code, and does not try to turn them into box-filling exercises when there's no good reason to. Likewise, when building functionality for your site, you should keep in mind that some features are destined to be maintained by the programmer rather than a content editor, and consider whether making them configurable through the Wagtail admin is going to be more of a hindrance than a convenience. For example, Wagtail provides a form builder to allow content authors to create general-purpose data collection forms. You might be tempted to use this as the basis for more complex forms that integrate with (for example) a CRM system or payment processor - however, in this case there's no way to edit the form fields without rewriting the backend logic, so making them editable through Wagtail has limited value. More likely, you'd be better off building these using Django's form framework, where the form fields are defined entirely in code.

docs/getting_started/tutorial.md

@@ -154,7 +154,7 @@ changes). You must run the above commands each time you make changes to
 the model definition.
 
 You can now edit the homepage within the Wagtail admin area (go to Pages, Homepage, then Edit) to see the new body field. Enter some text into the body field, and publish
-the page by selecting *Publish* at the bottom of the page editor, rather than *Save Draft*.
+the page by selecting _Publish_ at the bottom of the page editor, rather than _Save Draft_.
 
 The page template now needs to be updated to reflect the changes made
 to the model. Wagtail uses normal Django templates to render each page
@@ -201,9 +201,7 @@ of a `RichTextField`:
 Produces:
 
 ```html
-<p>
-    <b>Welcome</b> to our new site!
-</p>
+<p><b>Welcome</b> to our new site!</p>
 ```
 
 **Note:** You'll need to include `{% load wagtailcore_tags %}` in each
@@ -419,8 +417,8 @@ For more information, see: [Page QuerySet reference](../reference/pages/queryset
 
 There are a couple of problems with our blog index view:
 
-1)  Blogs generally display content in *reverse* chronological order
-2)  We want to make sure we're only displaying *published* content.
+1.  Blogs generally display content in _reverse_ chronological order
+2.  We want to make sure we're only displaying _published_ content.
 
 To accomplish these things, we need to do more than just grab the index
 page's children in the template. Instead, we'll want to modify the

docs/reference/contrib/forms/customisation.md

@@ -764,12 +764,12 @@ class FormPage(AbstractEmailForm):
 
 ## Custom `clean_name` generation
 
-* Each time a new `FormField` is added a `clean_name` also gets generated based on the user entered `label`.
-* `AbstractFormField` has a method `get_field_clean_name` to convert the label into a HTML valid `lower_snake_case` ASCII string using the [AnyAscii](https://pypi.org/project/anyascii/) library which can be overridden to generate a custom conversion.
-* The resolved `clean_name` is also used as the form field name in rendered HTML forms.
-* Ensure that any conversion will be unique enough to not create conflicts within your `FormPage` instance.
-* This method gets called on creation of new fields only and as such will not have access to its own `Page` or `pk`. This does not get called when labels are edited as modifying the `clean_name` after any form responses are submitted will mean those field responses will not be retrieved.
-* This method gets called for form previews and also validation of duplicate labels.
+-   Each time a new `FormField` is added a `clean_name` also gets generated based on the user entered `label`.
+-   `AbstractFormField` has a method `get_field_clean_name` to convert the label into a HTML valid `lower_snake_case` ASCII string using the [AnyAscii](https://pypi.org/project/anyascii/) library which can be overridden to generate a custom conversion.
+-   The resolved `clean_name` is also used as the form field name in rendered HTML forms.
+-   Ensure that any conversion will be unique enough to not create conflicts within your `FormPage` instance.
+-   This method gets called on creation of new fields only and as such will not have access to its own `Page` or `pk`. This does not get called when labels are edited as modifying the `clean_name` after any form responses are submitted will mean those field responses will not be retrieved.
+-   This method gets called for form previews and also validation of duplicate labels.
 
 ```python
     import uuid
@@ -793,4 +793,3 @@ class FormPage(AbstractEmailForm):
     class FormPage(AbstractEmailForm):
         # ... page definitions
 ```
-

docs/reference/contrib/legacy_richtext.md

@@ -1,11 +1,12 @@
 # Legacy richtext
 
 ```{module} wagtail.contrib.legacy.richtext
+
 ```
 
 Provides the legacy richtext wrapper.
 
-Place `wagtail.contrib.legacy.richtext` before `wagtail` in  `INSTALLED_APPS`.
+Place `wagtail.contrib.legacy.richtext` before `wagtail` in `INSTALLED_APPS`.
 
 ```python
 INSTALLED_APPS = [

docs/reference/contrib/modeladmin/base_url.md

@@ -1,19 +1,19 @@
-# Customising the base URL path
-
-You can use the following attributes and methods on the `ModelAdmin` class to alter the base URL path used to represent your model in Wagtail's admin area.
-
-```{contents}
----
-local:
-depth: 1
----
-```
-
-(modeladmin_base_url_path)=
-
-## `ModelAdmin.base_url_path`
-
-**Expected value**: A string.
-
-Set this attribute to a string value to override the default base URL path used for the model to `admin/{base_url_path}`.
-If not set, the base URL path will be `admin/{app_label}/{model_name}`.
+# Customising the base URL path
+
+You can use the following attributes and methods on the `ModelAdmin` class to alter the base URL path used to represent your model in Wagtail's admin area.
+
+```{contents}
+---
+local:
+depth: 1
+---
+```
+
+(modeladmin_base_url_path)=
+
+## `ModelAdmin.base_url_path`
+
+**Expected value**: A string.
+
+Set this attribute to a string value to override the default base URL path used for the model to `admin/{base_url_path}`.
+If not set, the base URL path will be `admin/{app_label}/{model_name}`.

docs/reference/pages/panels.md

@@ -93,7 +93,6 @@ This is a powerful but complex feature which will take some space to cover, so w
 Note that you can use `classname="collapsible collapsed"` to load the panel collapsed under its heading in order to save space in the Wagtail admin.
 See {ref}`collapsible` for more details on `collapsible` usage.
 
-
 ### FieldRowPanel
 
 ```{eval-rst}
@@ -248,11 +247,9 @@ By adding CSS classes to your panel definitions or adding extra parameters to yo
 Use `classname="full"` to make a field (input element) stretch the full width of the Wagtail page editor. This will not work if the field is encapsulated in a
 [`MultiFieldPanel`](wagtail.admin.panels.MultiFieldPanel), which places its child fields into a formset.
 
-
 ### Titles
 
-Use ``classname="title"`` to make Page's built-in title field stand out with more vertical padding.
-
+Use `classname="title"` to make Page's built-in title field stand out with more vertical padding.
 
 (collapsible)=
 
@@ -265,7 +262,6 @@ Use `classname="collapsible collapsed"` will load the editor page with the panel
 You must define a `heading` when using `collapsible` with `MultiFieldPanel`.
 You must define a `heading` or `label` when using `collapsible` with `InlinePanel`.
 
-
 ```python
     content_panels = [
         MultiFieldPanel(
@@ -318,17 +314,17 @@ class Book(models.Model):
 
 ### Required Fields
 
-To make input or chooser selection mandatory for a field, add [`blank=False`](<django.db.models.Field.blank>) to its model definition.
+To make input or chooser selection mandatory for a field, add [`blank=False`](django.db.models.Field.blank) to its model definition.
 
 ### Hiding Fields
 
-Without a panel definition, a default form field (without label) will be used to represent your fields. If you intend to hide a field on the Wagtail page editor, define the field with [`editable=False`](<django.db.models.Field.editable>).
+Without a panel definition, a default form field (without label) will be used to represent your fields. If you intend to hide a field on the Wagtail page editor, define the field with [`editable=False`](django.db.models.Field.editable).
 
 (inline_panels)=
 
 ## Inline Panels and Model Clusters
 
-The `django-modelcluster` module allows for streamlined relation of extra models to a Wagtail page via a ForeignKey-like relationship called `ParentalKey`.  Normally, your related objects "cluster" would need to be created beforehand (or asynchronously) before being linked to a Page; however, objects related to a Wagtail page via `ParentalKey` can be created on-the-fly and saved to a draft revision of a `Page` object.
+The `django-modelcluster` module allows for streamlined relation of extra models to a Wagtail page via a ForeignKey-like relationship called `ParentalKey`. Normally, your related objects "cluster" would need to be created beforehand (or asynchronously) before being linked to a Page; however, objects related to a Wagtail page via `ParentalKey` can be created on-the-fly and saved to a draft revision of a `Page` object.
 
 Let's look at the example of adding related links to a [`Page`](wagtail.models.Page)-derived model. We want to be able to add as many as we like, assign an order, and do all of this without leaving the page editing screen.
 

docs/releases/2.16.2.md

@@ -29,4 +29,4 @@ depth: 1
 
 ### Jinja2 compatibility
 
-Developers using Jinja2 templating should note that the template tags in this release (and earlier releases in the 2.15.x and 2.16.x series) are compatible with Jinja2 2.11.x and 3.0.x. Jinja2 2.11.x is unmaintained and requires ``markupsafe`` to be pinned to version ``<2.1`` to work; Jinja2 3.1.x has breaking changes and is not compatible. We therefore recommend that you use Jinja2 3.0.x, or 2.11.x with fully pinned dependencies.
+Developers using Jinja2 templating should note that the template tags in this release (and earlier releases in the 2.15.x and 2.16.x series) are compatible with Jinja2 2.11.x and 3.0.x. Jinja2 2.11.x is unmaintained and requires `markupsafe` to be pinned to version `<2.1` to work; Jinja2 3.1.x has breaking changes and is not compatible. We therefore recommend that you use Jinja2 3.0.x, or 2.11.x with fully pinned dependencies.

docs/releases/2.16.md

@@ -15,7 +15,6 @@ depth: 1
 
 This release adds support for Django 4.0.
 
-
 ### Slim sidebar
 
 As part of a [wider redesign](https://github.com/wagtail/wagtail/discussions/7739) of Wagtail’s administration interface, we have replaced the sidebar with a slim, keyboard-friendly version. This re-implementation comes with significant accessibility improvements for keyboard and screen reader users, and will enable us to make navigation between views much snappier in the future. Please have a look at [upgrade considerations](2.16_upgrade_considerations) for more details on differences with the previous version.
@@ -32,7 +31,6 @@ WAGTAILREDIRECTS_AUTO_CREATE = False
 
 Thank you to [The National Archives](https://www.nationalarchives.gov.uk) for kindly sponsoring this feature.
 
-
 ### Other features
 
  * Added persistent IDs for ListBlock items, allowing commenting and improvements to revision comparisons (Matt Westcott, Tidjani Dia, with sponsorship from [NHS](https://www.nhs.uk/))
@@ -87,6 +85,7 @@ Thank you to [The National Archives](https://www.nationalarchives.gov.uk) for ki
 
 
 (2.16_upgrade_considerations)=
+
 ## Upgrade considerations
 
 ### Removed support for Django 3.0 and 3.1

docs/releases/3.0.md

@@ -29,17 +29,14 @@ Other changes that are specific to the Page Editor include:
 
 Further updates to the page editor are expected in the next release. Development on this feature was sponsored by Google.
 
-
 ### Rich text block splitting
 
 Rich text blocks within StreamField now provide the ability to split a block at the cursor position, allowing new blocks to be inserted in between. This feature was developed by Jacob Topp-Mugglestone and sponsored by The Motley Fool.
 
-
 ### Removal of special-purpose field panel types
 
 The panel types `StreamFieldPanel`, `RichTextFieldPanel`, `ImageChooserPanel`, `DocumentChooserPanel` and `SnippetChooserPanel` have been phased out, and can now be replaced with `FieldPanel`. Additionally, `PageChooserPanel` is only required when passing a `page_type` or `can_choose_root`, and can otherwise be replaced with `FieldPanel`. In all cases, `FieldPanel` will now automatically select the most appropriate form element. This feature was developed by Matt Westcott.
 
-
 ### Permission-dependent FieldPanels
 
 [`FieldPanel`](wagtail.admin.panels.FieldPanel) now accepts a `permission` keyword argument to specify that the field should only be available to users with a given permission level. This feature was developed by Matt Westcott and sponsored by Google as part of Wagtail's page editor redevelopment.
@@ -246,6 +243,7 @@ The `data_json` field in the `BaseLogEntry` model (and its subclasses `PageLogEn
 The `form_data` field in the `AbstractFormSubmission` model (and its subclasses `FormSubmission`) has been converted to `JSONField` instead of `TextField`. If you have customisations that programmatically add form submissions you will need to ensure that the `form_data` that is output is no longer a JSON string but instead a serialisable Python object. When interacting with the `form_data` you will now receive a Python object and not a string.
 
 Example change
+
 ```
     def process_form_submission(self, form):
         self.get_submission_class().objects.create(

docs/releases/4.0.md

@@ -11,7 +11,7 @@ depth: 1
 
 ### Image renditions can now be prefetched by filter
 
-When using a queryset to render a list of images, you can now use the ``prefetch_renditions()`` queryset method to prefetch the renditions needed for rendering with a single extra query, similar to ``prefetch_related``. If you have many renditions per image, you can also call it with filters as arguments - ``prefetch_renditions("fill-700x586", "min-600x400")`` - to fetch only the renditions you intend on using for a smaller query. For long lists of images, this can provide a significant boost to performance. See [](prefetching_image_renditions) for more examples. This feature was developed by Tidiane Dia and Karl Hobley.
+When using a queryset to render a list of images, you can now use the `prefetch_renditions()` queryset method to prefetch the renditions needed for rendering with a single extra query, similar to `prefetch_related`. If you have many renditions per image, you can also call it with filters as arguments - `prefetch_renditions("fill-700x586", "min-600x400")` - to fetch only the renditions you intend on using for a smaller query. For long lists of images, this can provide a significant boost to performance. See [](prefetching_image_renditions) for more examples. This feature was developed by Tidiane Dia and Karl Hobley.
 
 ### Other features
 

docs/topics/pages.md

@@ -344,8 +344,8 @@ Each inline model requires the following:
 The model inlining feature is provided by [django-modelcluster](https://github.com/torchbox/django-modelcluster) and the `ParentalKey` field type must be imported from there:
 
 ```python
-    from modelcluster.fields import ParentalKey
-````
+from modelcluster.fields import ParentalKey
+```
 
 `ParentalKey` is a subclass of Django's `ForeignKey`, and takes the same arguments.
 
@@ -368,7 +368,7 @@ class BlogPageRelatedLink(Orderable):
         FieldPanel('name'),
         FieldPanel('url'),
     ]
-````
+```
 
 To add this to the admin interface, use the {class}`~wagtail.admin.panels.InlinePanel` edit panel class: