Move Markdown docs to MyST parser. Fix #8074 (#8084)

docs/advanced_topics/third_party_tutorials.md

@@ -1,6 +1,6 @@
 # Third-party tutorials
 
-```eval_rst warning::
+```{warning}
 The following list is a collection of tutorials and development notes
 from third-party developers. Some of the older links may not apply to
 the latest Wagtail versions.

docs/conf.py

@@ -18,7 +18,6 @@ from datetime import datetime
 
 import django
 import sphinx_wagtail_theme
-from recommonmark.transform import AutoStructify
 
 from wagtail import VERSION, __version__
 
@@ -57,7 +56,7 @@ os.environ["DATABASE_ENGINE"] = "django.db.backends.sqlite3"
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
-    "recommonmark",
+    "myst_parser",
     "sphinx_wagtail_theme",
 ]
 
@@ -299,14 +298,3 @@ texinfo_documents = [
 
 def setup(app):
     app.add_js_file("js/banner.js")
-
-    github_doc_root = "https://github.com/wagtail/wagtail/tree/main/docs/"
-
-    app.add_config_value(
-        "recommonmark_config",
-        {
-            "url_resolver": lambda url: github_doc_root + url,
-        },
-        True,
-    )
-    app.add_transform(AutoStructify)

docs/contributing/documentation_guidelines.md

@@ -1,14 +1,15 @@
 # Documentation guidelines
 
-```eval_rst
-.. contents::
-    :local:
-    :depth: 1
+```{contents}
+---
+local:
+depth: 1
+---
 ```
 
 ## Formatting recommendations
 
-Wagtail’s documentation uses a mixture of [Markdown](https://commonmark.org/help/) and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.
+Wagtail’s documentation uses a mixture of [Markdown](https://myst-parser.readthedocs.io/en/stable/syntax/syntax.html) and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.
 
 Here are formats we encourage using when writing documentation for Wagtail.
 
@@ -89,7 +90,7 @@ Don’t rely on [`links over code`](https://www.example.com/), as they are impos
 
 ```md
 An [external link](https://wwww.example.com).
-An [internal link to another document](/reference/contrib/legacy_richtext.md).
+An [internal link to another document](/reference/contrib/legacy_richtext).
 A [link to a reference](register_reports_menu_item).
 ```
 
@@ -98,35 +99,66 @@ A [link to a reference](register_reports_menu_item).
 <summary>Rendered output</summary>
 
 An [external link](https://wwww.example.com).
-An [internal link to another document](/reference/contrib/legacy_richtext.md).
+An [internal link to another document](/reference/contrib/legacy_richtext).
 A [link to a reference](register_reports_menu_item).
 
 </details>
 
-Reference links rely on creating a reference in reStructuredText. Prefer linking to the whole document if at all possible, otherwise create a reference by embedding reStructuredText with `eval_rst`:
+#### Reference links 
 
-    ```eval_rst
-    .. _register_reports_menu_item:
-    ```
+Reference links (links to a target within a page) rely on the page having a reference created, this can be added as follows:
+
+```md
+
+(my_awesome_section)=
+##### Some awesome section title
+
+...
+```
+
+The reference can be linked to, with an auto-generated label, using the Markdown link syntax as follows:
+
+```md
+[](my_awesome_section)
+```
+
+<details>
+
+<summary>Rendered output</summary>
+
+(my_awesome_section)=
+##### Some awesome section title
+
+...
+
+[](my_awesome_section)
+
+</details>
+
+You can read more about other methods of linking to, and creating references in the MyST parser docs section on [Targets and cross-referencing](https://myst-parser.readthedocs.io/en/stable/syntax/syntax.html#targets-and-cross-referencing).
 
 ### Note and warning call-outs
 
 Use notes and warnings sparingly, as they rely on reStructuredText syntax which is more complicated for future editors.
 
-    ```eval_rst note:: Notes can provide complementary information.
+    ```{note}
+    Notes can provide complementary information.
     ```
 
-    ```eval_rst warning:: Warnings can be scary.
+    ```{warning}
+    Warnings can be scary.
     ```
 
 <details>
 
 <summary>Rendered output</summary>
 
-```eval_rst note:: Notes can provide complementary information.
+```{note}
+Notes can provide complementary information.
 ```
 
-```eval_rst warning:: Warnings can be scary.
+```{warning}
+Warnings can be scary.
 ```
 
 </details>
@@ -155,7 +187,7 @@ Images are hard to keep up-to-date as documentation evolves, but can be worthwhi
 
 With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) feature, Sphinx supports writing documentation in Python docstrings for subsequent integration in the project’s documentation pages. This is a very powerful feature which we highly recommend using to document Wagtail’s APIs.
 
-    ```eval_rst
+    ```{eval-rst}
     .. module:: wagtail.core.utils
 
     .. autofunction:: cautious_slugify
@@ -164,7 +196,7 @@ With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc
 <details>
 <summary>Rendered output</summary>
 
-```eval_rst
+```{eval-rst}
 .. module:: wagtail.core.utils
 
 .. autofunction:: cautious_slugify
@@ -176,7 +208,7 @@ With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc
 
 Only use tables when needed, with the “simple” reStructuredText syntax, which is hard enough to format as it is.
 
-    ```eval_rst
+    ```{eval-rst}
     =============  =============
     Browser        Device/OS    
     =============  =============
@@ -190,7 +222,7 @@ Only use tables when needed, with the “simple” reStructuredText syntax, whic
 
 <summary>Rendered output</summary>
 
-```eval_rst
+```{eval-rst}
 =============  =============
 Browser        Device/OS    
 =============  =============
@@ -202,45 +234,44 @@ Safari         Windows
 
 </details>
 
-### Tables of content
-
-`toctree` and `contents` can be used as reStructuredText embeds.
+### Tables of contents
 
-    ```eval_rst
-    .. toctree::
-        :maxdepth: 2
-        :titlesonly:
+`toctree` and `contents` can be used as reStructuredText directives.
 
-        getting_started/index
-        topics/index
+    ```{toctree}
+    ---
+    maxdepth: 2
+    titlesonly:
+    ---
+    getting_started/index
+    topics/index
     ```
 
-    ```eval_rst
-    .. contents::
+    ```{contents}
+    ---
+    local:
+    depth: 1
+    ---
     ```
 
 ### Version added, changed, deprecations
 
 Sphinx offers release-metadata directives to generate this information consistently. Use as appropriate.
 
-    ```eval_rst
-    .. versionadded:: 2.15
+    ```{versionadded} 2.15
     ```
 
-    ```eval_rst
-    .. versionchanged:: 2.15
+    ```{versionchanged} 2.15
     ```
 
 <details>
 
 <summary>Rendered output</summary>
 
-```eval_rst
-.. versionadded:: 2.15
+```{versionadded} 2.15
 ```
 
-```eval_rst
-.. versionchanged:: 2.15
+```{versionchanged} 2.15
 ```
 
 </details>
@@ -275,7 +306,7 @@ There is some formatting in the documentation which is technically supported, bu
 
 ### Call-outs
 
-We only use `note::` and `warning::` call-outs. Avoid `important::`, `topic::`, and `tip::`. If you find one of these, please replace it with `note::`.
+We only use `{note}` and `{warning}` call-outs. Avoid `{important}`, `{topic}`, and `{tip}`. If you find one of these, please replace it with `{note}`.
 
 ### Glossary
 

docs/contributing/security.md

@@ -1,8 +1,7 @@
 # Reporting security issues
 
-```eval_rst
-.. note::
-   Please report security issues **only** to `security@wagtail.org <mailto:security@wagtail.org>`_.
+```{note}
+   Please report security issues **only** to [security@wagtail.org](mailto:security@wagtail.org).
 ```
 
 Most normal bugs in Wagtail are reported as [GitHub issues](https://github.com/wagtail/wagtail/issues), but due to the sensitive nature of security issues, we ask that they not be publicly reported in this fashion.

docs/extending/forms.md

@@ -26,7 +26,7 @@ the `date` and `image` fields on the form will use a date picker and image choos
 
 If you have implemented a form widget of your own, you can configure `WagtailAdminModelForm` to select it for a given model field type. This is done by calling the `wagtail.admin.forms.models.register_form_field_override` function, typically in an `AppConfig.ready` method.
 
-```eval_rst
+```{eval-rst}
 .. function:: register_form_field_override(model_field_class, to=None, override=None, exact_class=False)
 
    Specify a set of options that will override the form field's defaults when ``WagtailAdminModelForm`` encounters a given model field type.

docs/extending/template_components.md

@@ -1,10 +1,10 @@
 # Template components
 
-Working with objects that know how to render themselves as elements on an HTML template is a common pattern seen throughout the Wagtail admin. For example, the admin homepage is a view provided by the central `wagtail.admin` app, but brings together information panels sourced from various other modules of Wagtail, such as images and documents (potentially along with others provided by third-party packages). These panels are passed to the homepage via the [`construct_homepage_panels`](../reference/hooks.html#construct-homepage-panels) hook, and each one is responsible for providing its own HTML rendering. In this way, the module providing the panel has full control over how it appears on the homepage.
+Working with objects that know how to render themselves as elements on an HTML template is a common pattern seen throughout the Wagtail admin. For example, the admin homepage is a view provided by the central `wagtail.admin` app, but brings together information panels sourced from various other modules of Wagtail, such as images and documents (potentially along with others provided by third-party packages). These panels are passed to the homepage via the [`construct_homepage_panels`](construct_homepage_panels) hook, and each one is responsible for providing its own HTML rendering. In this way, the module providing the panel has full control over how it appears on the homepage.
 
 Wagtail implements this pattern using a standard object type known as a **component**. A component is a Python object that provides the following methods and properties:
 
-```eval_rst
+```{eval-rst}
 .. method:: render_html(self, parent_context=None)
 
 Given a context dictionary from the calling template (which may be a :py:class:`Context <django.template.Context>` object or a plain ``dict`` of context variables), returns the string representation to be inserted into the template. This will be subject to Django's HTML escaping rules, so a return value consisting of HTML should typically be returned as a :py:mod:`SafeString <django.utils.safestring>` instance.
@@ -12,14 +12,14 @@ Given a context dictionary from the calling template (which may be a :py:class:`
 .. attribute:: media
 
 A (possibly empty) :doc:`form media <django:topics/forms/media>` object defining JavaScript and CSS resources used by the component.
-
-.. note::
-   Any object implementing this API can be considered a valid component; it does not necessarily have to inherit from the ``Component`` class described below, and user code that works with components should not assume this (for example, it must not use ``isinstance`` to check whether a given value is a component).
 ```
 
-```eval_rst
-.. _creating_template_components:
+```{note}
+   Any object implementing this API can be considered a valid component; it does not necessarily have to inherit from the `Component` class described below, and user code that works with components should not assume this (for example, it must not use `isinstance` to check whether a given value is a component).
 ```
+
+(creating_template_components)=
+
 ## Creating components
 
 The preferred way to create a component is to define a subclass of `wagtail.admin.ui.components.Component` and specify a `template_name` attribute on it. The rendered template will then be used as the component's HTML representation:

docs/getting_started/index.md

@@ -1,15 +1,14 @@
-```eval_rst
+```{eval-rst}
 :hidetoc: 1
 ```
 
 # Getting started
 
-```eval_rst
-.. note::
+```{note}
    These instructions assume familiarity with virtual environments and the
-   `Django web framework <https://www.djangoproject.com/>`_.
-   For more detailed instructions, see :doc:`tutorial`.
-   To add Wagtail to an existing Django project, see :doc:`integrating_into_django`.
+   [Django web framework](https://www.djangoproject.com/).
+   For more detailed instructions, see [](tutorial).
+   To add Wagtail to an existing Django project, see [](integrating_into_django).
 ```
 
 ## Dependencies needed for installation
@@ -54,15 +53,15 @@ 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).
-
-```eval_rst
-.. toctree::
-    :maxdepth: 1
-
-    tutorial
-    demo_site
-    integrating_into_django
-    the_zen_of_wagtail
+- [Elasticsearch](/advanced_topics/performance).
+- [Feature Detection](image_feature_detection).
+
+```{toctree}
+---
+maxdepth: 1
+---
+tutorial
+demo_site
+integrating_into_django
+the_zen_of_wagtail
 ```

docs/getting_started/integrating_into_django.md

@@ -1,6 +1,3 @@
-```eval_rst
-.. _integrating_into_django:
-```
 # Integrating Wagtail into a Django project
 
 Wagtail provides the `wagtail start` command and project template to get you started with a new Wagtail project as quickly as possible, but it's easy to integrate Wagtail into an existing Django project too.

docs/getting_started/the_zen_of_wagtail.md

@@ -26,7 +26,7 @@ Suppose a content author comes to you with a request: "We need this text to be i
 
 A common sight in content management systems is a point-and-click interface to let you define the data model that makes up a page:
 
-![](../_static/images/drupal_content_type.png)
+![Image of a CMS interface](../_static/images/drupal_content_type.png)
 
 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.
 

docs/getting_started/tutorial.md

@@ -1,9 +1,8 @@
 # Your first Wagtail site
 
-```eval_rst
-.. note::
-   This tutorial covers setting up a brand new Wagtail project.
-   If you'd like to add Wagtail to an existing Django project instead, see :doc:`integrating_into_django`.
+```{note}
+This tutorial covers setting up a brand new Wagtail project.
+If you'd like to add Wagtail to an existing Django project instead, see [](integrating_into_django).
 ```
 
 ## Install and run Wagtail
@@ -20,11 +19,10 @@ $ python3 --version
 
 If this does not return a version number or returns a version lower than 3.7, you will need to [install Python 3](https://www.python.org/downloads/).
 
-```eval_rst
-.. important::
+```{important}
    Before installing Wagtail, it is necessary to install the **libjpeg** and **zlib** libraries, which provide support for working with JPEG, PNG and GIF images (via the Python **Pillow** library).
    The way to do this varies by platform—see Pillow's
-   `platform-specific installation instructions <https://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
+   [platform-specific installation instructions](https://pillow.readthedocs.org/en/latest/installation.html#external-libraries).
 ```
 
 ### Create and activate a virtual environment
@@ -48,11 +46,9 @@ $ source mysite/env/bin/activate
 
 **For other shells** see the [`venv` documentation](https://docs.python.org/3/library/venv.html).
 
-```eval_rst
-.. note::
-
-   If you're using version control (e.g. git), ``mysite`` will be the directory for your project.
-   The ``env`` directory inside of it should be excluded from any version control.
+```{note}
+If you're using version control (e.g. git), `mysite` will be the directory for your project.
+The `env` directory inside of it should be excluded from any version control.
 ```
 
 ### Install Wagtail
@@ -77,10 +73,8 @@ Because the folder `mysite` was already created by `venv`, run `wagtail start` w
 $ wagtail start mysite mysite
 ```
 
-```eval_rst
-.. note::
-
-   Generally, in Wagtail, each page type, or content type, is represented by a single app. However, different apps can be aware of each other and   access each other's data. All of the apps need to be registered within the ``INSTALLED_APPS`` section of the ``settings`` file. Look at this file to see how the ``start`` command has listed them in there.
+```{note}
+Generally, in Wagtail, each page type, or content type, is represented by a single app. However, different apps can be aware of each other and access each other's data. All of the apps need to be registered within the `INSTALLED_APPS` section of the `settings` file. Look at this file to see how the `start` command has listed them in there.
 ```
 
 ### Install project dependencies
@@ -761,9 +755,7 @@ something like this:
 
 ![](../_static/images/tutorial/tutorial_9.png)
 
-```eval_rst
-.. _tutorial_categories:
-```
+(tutorial_categories)=
 
 ### Categories
 
@@ -795,9 +787,8 @@ class BlogCategory(models.Model):
         verbose_name_plural = 'blog categories'
 ```
 
-```eval_rst
-.. note::
-   Note that we are using ``panels`` rather than ``content_panels`` here - since snippets generally have no need for fields such as slug or publish date, the editing interface for them is not split into separate 'content' / 'promote' / 'settings' tabs as standard, and so there is no need to distinguish between 'content panels' and 'promote panels'.
+```{note}
+Note that we are using `panels` rather than `content_panels` here - since snippets generally have no need for fields such as slug or publish date, the editing interface for them is not split into separate 'content' / 'promote' / 'settings' tabs as standard, and so there is no need to distinguish between 'content panels' and 'promote panels'.
 ```
 
 Migrate this change in, and create a few categories through the Snippets area which now appears in the admin menu.

docs/reference/contrib/legacy_richtext.md

@@ -1,7 +1,6 @@
 # Legacy richtext
 
-```eval_rst
-.. module:: wagtail.contrib.legacy.richtext
+```{module} wagtail.contrib.legacy.richtext
 ```
 
 Provides the legacy richtext wrapper.

docs/releases/2.16.2.md

@@ -1,9 +1,10 @@
 # Wagtail 2.16.2 release notes - IN DEVELOPMENT
 
-```eval_rst
-.. contents::
-    :local:
-    :depth: 1
+```{contents}
+---
+local:
+depth: 1
+---
 ```
 
 ## What's new

docs/releases/2.16.md

@@ -1,9 +1,10 @@
 # Wagtail 2.16 release notes
 
-```eval_rst
-.. contents::
-    :local:
-    :depth: 1
+```{contents}
+---
+local:
+depth: 1
+---
 ```
 
 ## What's new

docs/releases/2.17.md

@@ -1,9 +1,10 @@
 # Wagtail 2.17 release notes - IN DEVELOPMENT
 
-```eval_rst
-.. contents::
-    :local:
-    :depth: 1
+```{contents}
+---
+local:
+depth: 1
+---
 ```
 
 ## What's new

docs/requirements.txt

@@ -1,2 +1,3 @@
-docutils==0.16  # Pinned to work around https://github.com/sphinx-doc/sphinx/issues/9049
+docutils==0.17
+myst_parser==0.17.0
 sphinx-wagtail-theme==5.0.4

docs/topics/index.md

@@ -1,15 +1,15 @@
 # Usage guide
 
-```eval_rst
-.. toctree::
-    :maxdepth: 2
-    :titlesonly:
-
-    pages
-    writing_templates
-    images
-    search/index
-    snippets
-    streamfield
-    permissions
+```{toctree}
+---
+maxdepth: 2
+titlesonly:
+---
+pages
+writing_templates
+images
+search/index
+snippets
+streamfield
+permissions
 ```

docs/topics/pages.md

@@ -1,18 +1,14 @@
 # Page models
 
-```eval_rst
-Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the :class:`wagtail.core.models.Page` class.
-```
+Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the {class}`wagtail.core.models.Page` class.
 
 As all page types are Django models, you can use any field type that Django provides. See [Model field reference](https://docs.djangoproject.com/en/stable/ref/models/fields/) for a complete list of field types you can use. Wagtail also provides `wagtail.core.fields.RichTextField` which provides a WYSIWYG editor for editing rich-text content.
 
-```eval_rst
-.. note::
-
-    If you're not yet familiar with Django models, have a quick look at the following links to get you started:
+```{note}
+If you're not yet familiar with Django models, have a quick look at the following links to get you started:
 
-    * :ref:`Creating models <django:creating-models>`
-    * :doc:`Model syntax <django:topics/db/models>`
+* {ref}`Creating models <django:creating-models>`
+* {doc}`Model syntax <django:topics/db/models>`
 ```
 
 ## An example Wagtail page model
@@ -84,10 +80,8 @@ class BlogPageRelatedLink(Orderable):
     ]
 ```
 
-```eval_rst
-.. note::
-
-    Ensure that none of your field names are the same as your class names. This will cause errors due to the way Django handles relations (`read more <https://github.com/wagtail/wagtail/issues/503>`_). In our examples we have avoided this by appending "Page" to each model name.
+```{note}
+Ensure that none of your field names are the same as your class names. This will cause errors due to the way Django handles relations ([read more](https://github.com/wagtail/wagtail/issues/503)). In our examples we have avoided this by appending "Page" to each model name.
 ```
 
 ## Writing page models
@@ -135,34 +129,27 @@ Here's a summary of the `EditHandler` classes that Wagtail provides out of the b
 
 These allow editing of model fields. The `FieldPanel` class will choose the correct widget based on the type of the field, such as a rich text editor for `RichTextField`, or an image chooser for a `ForeignKey` to an image model. `FieldPanel` also provides a page chooser interface for `ForeignKey`s to page models, but for more fine-grained control over which page types can be chosen, `PageChooserPanel` provides additional configuration options.
 
-```eval_rst
--   :class:`~wagtail.admin.edit_handlers.FieldPanel`
--   :class:`~wagtail.admin.edit_handlers.PageChooserPanel`
+- {class}`~wagtail.admin.edit_handlers.FieldPanel`
+- {class}`~wagtail.admin.edit_handlers.PageChooserPanel`
 
-.. versionchanged:: 2.17
-
-   Previously, certain field types required special-purpose panels: ``StreamFieldPanel``, ``ImageChooserPanel``, ``DocumentChooserPanel`` and ``SnippetChooserPanel``. These are now all handled by ``FieldPanel``.
+```{versionchanged} 2.17
+Previously, certain field types required special-purpose panels: `StreamFieldPanel`, `ImageChooserPanel`, `DocumentChooserPanel` and `SnippetChooserPanel`. These are now all handled by `FieldPanel`.
 ```
 
-
 **Structural**
 
 These are used for structuring fields in the interface.
 
-```eval_rst
--   :class:`~wagtail.admin.edit_handlers.MultiFieldPanel`
--   :class:`~wagtail.admin.edit_handlers.InlinePanel`
--   :class:`~wagtail.admin.edit_handlers.FieldRowPanel`
-```
+- {class}`~wagtail.admin.edit_handlers.MultiFieldPanel`
+- {class}`~wagtail.admin.edit_handlers.InlinePanel`
+- {class}`~wagtail.admin.edit_handlers.FieldRowPanel`
 
 
 #### Customising the page editor interface
 
 The page editor can be customised further. See [Customising the editing interface](/advanced_topics/customisation/page_editing_interface).
 
-```eval_rst
-.. _page_type_business_rules:
-```
+(page_type_business_rules)=
 ### Parent page / subpage type rules
 
 These two attributes allow you to control where page types may be used in your site. It allows you to define rules like "blog entries may only be created under a blog index".
@@ -176,9 +163,7 @@ By default, any page type can be created under any page type and it is not neces
 
 Setting `parent_page_types` to an empty list is a good way of preventing a particular page type from being created in the editor interface.
 
-```eval_rst
-.. _page_urls:
-```
+(page_urls)=
 ### Page URLs
 
 The most common method of retrieving page URLs is by using the `{% pageurl %}` template tag. Since it's called from a template, `pageurl` automatically includes the optimizations mentioned below. For more information, see [pageurl](pageurl_tag).
@@ -204,9 +189,7 @@ super().get_url_parts(*args, **kwargs)
 While you could pass only the `request` keyword argument, passing all arguments as-is ensures compatibility with any
 future changes to these method signatures.
 
-```eval_rst
-For more information, please see :meth:`wagtail.core.models.Page.get_url_parts`.
-```
+For more information, please see {meth}`wagtail.core.models.Page.get_url_parts`.
 
 #### Obtaining URLs for page instances
 
@@ -215,15 +198,11 @@ The `Page.get_url(request)` method can be called whenever a page URL is needed.
 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
 request or `None` if no request exists in the context.
 
-```eval_rst
-For more information, please see :meth:`wagtail.core.models.Page.get_url`.
-```
+For more information, please see {meth}`wagtail.core.models.Page.get_url`.
 
 In the event a full URL (including the protocol and domain) is needed, `Page.get_full_url(request)` can be used instead. Whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information.
 
-```eval_rst
-For more information, please see :meth:`wagtail.core.models.Page.get_full_url`.
-```
+For more information, please see {meth}`wagtail.core.models.Page.get_full_url`.
 
 ## Template rendering
 
@@ -345,19 +324,17 @@ Wagtail can nest the content of other models within the page. This is useful for
 
 Each inline model requires the following:
 
-```eval_rst
--   It must inherit from :class:`wagtail.core.models.Orderable`
--   It must have a `ParentalKey` to the parent model
-
-.. note:: django-modelcluster and ParentalKey
+- It must inherit from {class}`wagtail.core.models.Orderable`
+- It must have a `ParentalKey` to the parent model
 
-    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:
+```{note} django-modelcluster and ParentalKey
+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:
 
-    .. code-block:: python
-
-        from modelcluster.fields import ParentalKey
+```python
+    from modelcluster.fields import ParentalKey
+```
 
-    ``ParentalKey`` is a subclass of Django's ``ForeignKey``, and takes the same arguments.
+`ParentalKey` is a subclass of Django's `ForeignKey`, and takes the same arguments.
 ```
 
 For example, the following inline model can be used to add related links (a list of name, url pairs) to the `BlogPage` model:
@@ -379,9 +356,7 @@ class BlogPageRelatedLink(Orderable):
     ]
 ```
 
-```eval_rst
-To add this to the admin interface, use the :class:`~wagtail.admin.edit_handlers.InlinePanel` edit panel class:
-```
+To add this to the admin interface, use the {class}`~wagtail.admin.edit_handlers.InlinePanel` edit panel class:
 
 ```python
 content_panels = [
@@ -397,9 +372,7 @@ The first argument must match the value of the `related_name` attribute of the `
 
 Wagtail uses Django's [multi-table inheritance](https://docs.djangoproject.com/en/3.1/topics/db/models/#multi-table-inheritance) feature to allow multiple page models to be used in the same tree.
 
-```eval_rst
-Each page is added to both Wagtail's builtin :class:`~wagtail.core.models.Page` model as well as its user-defined model (such as the `BlogPage` model created earlier).
-```
+Each page is added to both Wagtail's builtin {class}`~wagtail.core.models.Page` model as well as its user-defined model (such as the `BlogPage` model created earlier).
 
 Pages can exist in Python code in two forms, an instance of `Page` or an instance of the page model.
 
@@ -468,9 +441,7 @@ This is because `Page` enforces ordering QuerySets by path. Instead, you must ap
 news_items = NewsItemPage.objects.live().order_by('-publication_date')
 ```
 
-```eval_rst
-.. _custom_page_managers:
-```
+(custom_page_managers)=
 ### Custom Page managers
 
 You can add a custom `Manager` to your `Page` class. Any custom Managers should inherit from `wagtail.core.models.PageManager`:

setup.py

@@ -79,7 +79,7 @@ documentation_extras = [
     "Sphinx>=1.5.2",
     "sphinx-autobuild>=0.6.0",
     "sphinx-wagtail-theme==5.0.4",
-    "recommonmark>=0.7.1",
+    "myst_parser==0.17.0",
 ]
 
 setup(