documentation - convert contributing files from rst to markdown

docs/contributing/committing.md

@@ -1,6 +1,4 @@
-===============
-Committing code
-===============
+# Committing code
 
 **This section is for the core team of Wagtail, or for anyone interested in the process of getting code committed to Wagtail.**
 
@@ -15,34 +13,32 @@ Most code contributions will be in the form of pull requests from Github.
 Pull requests should not be merged from Github, apart from small documentation fixes,
 which can be merged with the 'Squash and merge' option. Instead, the code should
 be checked out by a committer locally, the changes examined and rebased,
-the ``CHANGELOG.txt`` and release notes updated,
-and finally the code should be pushed to the ``main`` branch.
+the `CHANGELOG.txt` and release notes updated,
+and finally the code should be pushed to the `main` branch.
 This process is covered in more detail below.
 
-Check out the code locally
-==========================
+## Check out the code locally
 
 If the code has been submitted as a pull request,
 you should fetch the changes and check them out in your Wagtail repository.
-A simple way to do this is by adding the following ``git`` alias to your ``~/.gitconfig`` (assuming ``upstream`` is ``wagtail/wagtail``):
+A simple way to do this is by adding the following `git` alias to your `~/.gitconfig` (assuming `upstream` is `wagtail/wagtail`):
 
-.. code-block:: text
+```text
+[alias]
+    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
+```
 
-    [alias]
-        pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
+Now you can check out pull request number `xxxx` by running `git pr xxxx`.
 
-Now you can check out pull request number ``xxxx`` by running ``git pr xxxx``.
+## Rebase on to `main`
 
-Rebase on to ``main``
-=====================
-
-Now that you have the code, you should rebase the commits on to the ``main`` branch.
+Now that you have the code, you should rebase the commits on to the `main` branch.
 Rebasing is preferred over merging,
 as merge commits make the commit history harder to read for small changes.
 
 You can fix up any small mistakes in the commits,
 such as typos and formatting, as part of the rebase.
-``git rebase --interactive`` is an excellent tool for this job.
+`git rebase --interactive` is an excellent tool for this job.
 
 Ideally, use this as an opportunity to squash the changes to a few commits, so
 each commit is making a single meaningful change (and not breaking anything).
@@ -50,49 +46,48 @@ If this is not possible because of the nature of the changes, it's acceptable
 to either squash into a commit or leave all commits unsquashed,
 depending on which will be more readable in the commit history.
 
-.. code-block:: console
-
-    $ # Get the latest commits from Wagtail
-    $ git fetch upstream
-    $ git checkout main
-    $ git merge --ff-only upstream/main
-    $ # Rebase this pull request on to main
-    $ git checkout pr/xxxx
-    $ git rebase main
-    $ # Update main to this commit
-    $ git checkout main
-    $ git merge --ff-only pr/xxxx
-
-Update ``CHANGELOG.txt`` and release notes
-==========================================
-
-.. note::
-
-    This should only be done by core committers, once the changes have been reviewed and accepted.
-
-Every significant change to Wagtail should get an entry in the ``CHANGELOG.txt``,
+```console
+# Get the latest commits from Wagtail
+git fetch upstream
+git checkout main
+git merge --ff-only upstream/main
+# Rebase this pull request on to main
+git checkout pr/xxxx
+git rebase main
+# Update main to this commit
+git checkout main
+git merge --ff-only pr/xxxx
+```
+
+## Update `CHANGELOG.txt` and release notes
+
+```{note}
+This should only be done by core committers, once the changes have been reviewed and accepted.
+```
+
+Every significant change to Wagtail should get an entry in the `CHANGELOG.txt`,
 and the release notes for the current version.
 
-The ``CHANGELOG.txt`` contains a short summary of each new feature, refactoring, or bug fix in each release.
+The `CHANGELOG.txt` contains a short summary of each new feature, refactoring, or bug fix in each release.
 Each summary should be a single line.
 Bug fixes should be grouped together at the end of the list for each release,
 and be prefixed with "Fix:".
 The name of the contributor should be added at the end of the summary, in brackets.
 For example:
 
-.. code-block:: text
-
-     * Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)
+```text
+* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)
+```
 
 The release notes for each version contain a more detailed description of each change.
 Backwards compatibility notes should also be included.
 Large new features or changes should get their own section,
 while smaller changes and bug fixes should be grouped together in their own section.
 See previous release notes for examples.
-The release notes for each version are found in ``docs/releases/x.x.x.rst``.
+The release notes for each version are found in `docs/releases/x.x.x.md`.
 
 If the contributor is a new person, and this is their first contribution to Wagtail,
-they should be added to the ``CONTRIBUTORS.rst`` list.
+they should be added to the `CONTRIBUTORS.rst` list.
 Contributors are added in chronological order,
 with new contributors added to the bottom of the list.
 Use their preferred name.
@@ -101,60 +96,56 @@ If in doubt, or if their name is not on their profile, ask them how they want to
 
 If the changes to be merged are small enough to be a single commit,
 amend this single commit with the additions to
-the ``CHANGELOG.txt``, release notes, and contributors:
-
-.. code-block:: console
+the `CHANGELOG.txt`, release notes, and contributors:
 
-    $ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
-    $ git commit --amend --no-edit
+```console
+git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
+git commit --amend --no-edit
+```
 
 If the changes do not fit in a single commit, make a new commit with the updates to
-the ``CHANGELOG.txt``, release notes, and contributors.
-The commit message should say ``Release notes for #xxxx``:
-
-.. code-block:: console
+the `CHANGELOG.txt`, release notes, and contributors.
+The commit message should say `Release notes for #xxxx`:
 
-    $ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
-    $ git commit -m 'Release notes for #xxxx'
+```console
+git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
+git commit -m 'Release notes for #xxxx'
+```
 
-Push to ``main``
-================
+## Push to `main`
 
-The changes are ready to be pushed to ``main`` now.
+The changes are ready to be pushed to `main` now.
 
-.. code-block:: console
+```console
+# Check that everything looks OK
+git log upstream/main..main --oneline
+git push --dry-run upstream main
+# Push the commits!
+git push upstream main
+git branch -d pr/xxxx
+```
 
-    $ # Check that everything looks OK
-    $ git log upstream/main..main --oneline
-    $ git push --dry-run upstream main
-    $ # Push the commits!
-    $ git push upstream main
-    $ git branch -d pr/xxxx
-
-When you have made a mistake
-============================
+## When you have made a mistake
 
 It's ok! Everyone makes mistakes. If you realise that recent merged changes
 have a negative impact, create a new pull request with a revert of the changes
 and merge it without waiting for a review. The PR will serve as additional
 documentation for the changes, and will run through the CI tests.
 
-
-Add commits to someone else's pull request
-==========================================
+## Add commits to someone else's pull request
 
 Github users with write access to wagtail/wagtail (core members) can add
 commits to the pull request branch of the contributor.
 
 Given that the contributor username is johndoe and his pull request branch is called foo:
 
-.. code-block:: console
-
-    $ git clone git@github.com:wagtail/wagtail.git
-    $ cd wagtail
-    $ git remote add johndoe git@github.com:johndoe/wagtail.git
-    $ git fetch johndoe foo
-    $ git checkout johndoe/foo
-    # Make changes
-    # Commit changes
-    $ git push johndoe HEAD:foo
+```console
+git clone git@github.com:wagtail/wagtail.git
+cd wagtail
+git remote add johndoe git@github.com:johndoe/wagtail.git
+git fetch johndoe foo
+git checkout johndoe/foo
+# Make changes
+# Commit changes
+git push johndoe HEAD:foo
+```

docs/contributing/developing.md

@@ -1,4 +1,4 @@
-(developing)=
+(developing_for_wagtail)=
 
 # Development
 

docs/contributing/documentation_modes.md

@@ -1,23 +1,18 @@
-Writing documentation
-=====================
-
-.. rst-class:: intro
+# Writing documentation
 
 Wagtail documentation is written in **four modes** of information delivery.
 Each type of information delivery has a purpose and targets a specific audience.
 
-* :ref:`doc-mode-tutorial`, learning-oriented
-* :ref:`doc-mode-how-to-guide`, goal-oriented
-* :ref:`doc-mode-reference`, information-oriented
-* :ref:`doc-mode-explanation`, understanding-oriented
-
-We are following Daniele Procida's `Diátaxis documentation framework <https://diataxis.fr/>`__.
+-   [](doc_mode_tutorial), learning-oriented
+-   [](doc_mode_how_to_guide), goal-oriented
+-   [](doc_mode_reference), information-oriented
+-   [](doc_mode_explanation), understanding-oriented
 
+We are following Daniele Procida's [Diátaxis documentation framework](https://diataxis.fr/).
 
-.. _choose-a-writing-mode:
+(choose-a-writing-mode)=
 
-Choose a writing mode
----------------------
+## Choose a writing mode
 
 Each page of the Wagtail documentation should be written in single mode of information delivery.
 Single pages with mixed modes are harder to understand.
@@ -26,66 +21,56 @@ it’s best to split them up. Add links to the first section of each document to
 
 Writing documentation in a specific mode will help our users to understand and quickly find what they are looking for.
 
-.. _doc-mode-tutorial:
+(doc_mode_tutorial)=
 
-Tutorial
---------
+## Tutorial
 
 Tutorials are designed to be **learning-oriented** resources which guide newcomers through a specific topic. To help effective learning, tutorials should provide examples to illustrate the subjects they cover.
 
 Tutorials may not necessarily follow best practices. They are designed to make it easier to get started. A tutorial is concrete and particular. It must be repeatable, instil confidence, and should result in success, every time, for every learner.
 
-Do
-~~
-
-- Use conversational language
-- Use contractions, speak in the first person plural,
-  be reassuring. For example: “We’re going to do this.”
-- Use pictures or concrete outputs of code to reassure people that they’re on the right track.
-  For example: “Your new login page should look like this:” or “Your directory should now have three files”.
+### Do
 
-Don’t
-~~~~~
+-   Use conversational language
+-   Use contractions, speak in the first person plural,
+    be reassuring. For example: “We’re going to do this.”
+-   Use pictures or concrete outputs of code to reassure people that they’re on the right track.
+    For example: “Your new login page should look like this:” or “Your directory should now have three files”.
 
-- Tell people what they’re going to learn.
-  Instead, tell them what tasks they’re going to complete.
-- Use optionality in a tutorial. The word ‘if’ is a sign of danger!
-  For example: “If you want to do this…”
-  The expected actions and outcomes should be unambiguous.
-- Assume that learners have a prior understanding of the subject.
+### Don’t
 
-`More about tutorials <https://diataxis.fr/tutorials/>`__
+-   Tell people what they’re going to learn.
+    Instead, tell them what tasks they’re going to complete.
+-   Use optionality in a tutorial. The word ‘if’ is a sign of danger!
+    For example: “If you want to do this…”
+    The expected actions and outcomes should be unambiguous.
+-   Assume that learners have a prior understanding of the subject.
 
+[More about tutorials](https://diataxis.fr/tutorials/)
 
-.. _doc-mode-how-to-guide:
+(doc_mode_how_to_guide)=
 
-How-to guide
-------------
+## How-to guide
 
 A guide offers advice on how best to achieve a given task.
 How-to guides are **task-oriented** with a clear **goal or objective**.
 
-Do
-~~
+### Do
 
-- Name the guide well - ensure that the learner understands what exactly the guide does.
-- Focus on actions and outcomes. For example: “If you do X, Y should happen.”
-- Assume that the learner has a basic understanding of the general concepts
-- Point the reader to additional resources
+-   Name the guide well - ensure that the learner understands what exactly the guide does.
+-   Focus on actions and outcomes. For example: “If you do X, Y should happen.”
+-   Assume that the learner has a basic understanding of the general concepts
+-   Point the reader to additional resources
 
+### Don’t
 
-Don’t
-~~~~~
+-   Use an unnecessarily strict tone of voice. For example: “You must absolutely NOT do X.”
 
-- Use an unnecessarily strict tone of voice. For example: “You must absolutely NOT do X.”
+[More about how-to guides](https://diataxis.fr/how-to-guides/)
 
-`More about how-to guides <https://diataxis.fr/how-to-guides/>`__
+(doc_mode_reference)=
 
-
-.. _doc-mode-reference:
-
-Reference
----------
+## Reference
 
 Reference material is **information-oriented**.
 A reference is well-structured and allows the reader to find information about a specific topic.
@@ -94,13 +79,11 @@ For example: “Inherit from the Page model”.
 
 Most references will be auto-generated based on doc-strings in the Python code.
 
-`More about reference <https://diataxis.fr/reference/>`__
-
+[More about reference](https://diataxis.fr/reference/)
 
-.. _doc-mode-explanation:
+(doc_mode_explanation)=
 
-Explanation
------------
+## Explanation
 
 Explanations are **understanding-oriented**.
 They are high-level and offer context to concepts and design decisions.
@@ -108,4 +91,4 @@ There is little or no code involved in explanations,
 which are used to deepen the theoretical understanding of a practical draft.
 Explanations are used to establish connections and may require some prior knowledge of the principles being explored.
 
-`More about explanation <https://diataxis.fr/explanation/>`__
+[More about explanation](https://diataxis.fr/explanation/)

docs/contributing/index.md

@@ -1,70 +1,62 @@
-Contributing to Wagtail
-=======================
+# Contributing to Wagtail
 
-Issues
-~~~~~~
+## Issues
 
-The easiest way to contribute to Wagtail is to tell us how to improve it! First, check to see if your bug or feature request has already been submitted at `github.com/wagtail/wagtail/issues <https://github.com/wagtail/wagtail/issues>`_. If it has, and you have some supporting information which may help us deal with it, comment on the existing issue. If not, please `create a new one <https://github.com/wagtail/wagtail/issues/new>`_, providing as much relevant context as possible. For example, if you're experiencing problems with installation, detail your environment and the steps you've already taken. If something isn't displaying correctly, tell us what browser you're using, and include a screenshot if possible.
+The easiest way to contribute to Wagtail is to tell us how to improve it! First, check to see if your bug or feature request has already been submitted at [github.com/wagtail/wagtail/issues](https://github.com/wagtail/wagtail/issues). If it has, and you have some supporting information which may help us deal with it, comment on the existing issue. If not, please [create a new one](https://github.com/wagtail/wagtail/issues/new), providing as much relevant context as possible. For example, if you're experiencing problems with installation, detail your environment and the steps you've already taken. If something isn't displaying correctly, tell us what browser you're using, and include a screenshot if possible.
 
-If your bug report is a security issue, **do not** report it with an issue. Please read our ​guide to :doc:`reporting security issues <security>`.
+If your bug report is a security issue, **do not** report it with an issue. Please read our ​guide to [reporting security issues](security).
 
-.. toctree::
-    :maxdepth: 2
+```{toctree}
+:maxdepth: 2
 
-    issue_tracking
+issue_tracking
+```
 
-Pull requests
-~~~~~~~~~~~~~
+## Pull requests
 
-If you're a Python or Django developer, `fork it <https://github.com/wagtail/wagtail/>`_ and read the :ref:`developing docs <developing>` to get stuck in! We welcome all contributions, whether they solve problems which are specific to you or they address existing issues. If you're stuck for ideas, pick something from the `issue list <https://github.com/wagtail/wagtail/issues?state=open>`_, or email us directly on `hello@wagtail.org <mailto:hello@wagtail.org>`_ if you'd like us to suggest something!
+If you're a Python or Django developer, [fork it](https://github.com/wagtail/wagtail/) and read the [developing docs](developing_for_wagtail) to get stuck in! We welcome all contributions, whether they solve problems which are specific to you or they address existing issues. If you're stuck for ideas, pick something from the [issue list](https://github.com/wagtail/wagtail/issues?state=open), or email us directly on [hello@wagtail.org](mailto:hello@wagtail.org) if you'd like us to suggest something!
 
-For large-scale changes, we'd generally recommend breaking them down into smaller pull requests that achieve a single well-defined task and can be reviewed individually. If this isn't possible, we recommend opening a pull request on the `Wagtail RFCs <https://github.com/wagtail/rfcs/>`_ repository, so that there's a chance for the community to discuss the change before it gets implemented.
+For large-scale changes, we'd generally recommend breaking them down into smaller pull requests that achieve a single well-defined task and can be reviewed individually. If this isn't possible, we recommend opening a pull request on the [Wagtail RFCs](https://github.com/wagtail/rfcs/) repository, so that there's a chance for the community to discuss the change before it gets implemented.
 
-.. toctree::
-    :maxdepth: 2
+```{toctree}
+:maxdepth: 2
 
-    developing
-    committing
+developing
+committing
+```
 
-
-Translations
-~~~~~~~~~~~~
+## Translations
 
 Wagtail has internationalisation support so if you are fluent in a non-English language you can contribute by localising the interface.
 
-Translation work should be submitted through `Transifex <https://www.transifex.com/projects/p/wagtail/>`_.
-
-
-Other contributions
-~~~~~~~~~~~~~~~~~~~
-
-We welcome contributions to all aspects of Wagtail. If you would like to improve the design of the user interface, or extend the documentation, please submit a pull request as above. If you're not familiar with Github or pull requests, `contact us directly <mailto:hello@wagtail.org>`_ and we'll work something out.
+Translation work should be submitted through [Transifex](https://www.transifex.com/projects/p/wagtail/).
 
+## Other contributions
 
+We welcome contributions to all aspects of Wagtail. If you would like to improve the design of the user interface, or extend the documentation, please submit a pull request as above. If you're not familiar with Github or pull requests, [contact us directly](mailto:hello@wagtail.org) and we'll work something out.
 
-Developing packages for Wagtail
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you are developing packages for Wagtail, you can add the following `PyPI <https://pypi.org/>`_ classifiers:
+## Developing packages for Wagtail
 
-* `Framework :: Wagtail <https://pypi.org/search/?c=Framework+%3A%3A+Wagtail>`_
-* `Framework :: Wagtail :: 1 <https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+1>`_
-* `Framework :: Wagtail :: 2 <https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+2>`_
-* `Framework :: Wagtail :: 3 <https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+3>`_
+If you are developing packages for Wagtail, you can add the following [PyPI](https://pypi.org/) classifiers:
 
-You can also find a curated list of awesome packages, articles, and other cool resources from the Wagtail community at `Awesome Wagtail <https://github.com/springload/awesome-wagtail>`_.
+-   [`Framework :: Wagtail`](https://pypi.org/search/?c=Framework+%3A%3A+Wagtail)
+-   [`Framework :: Wagtail :: 1`](https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+1)
+-   [`Framework :: Wagtail :: 2`](https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+2)
+-   [`Framework :: Wagtail :: 3`](https://pypi.org/search/?c=Framework+%3A%3A+Wagtail+%3A%3A+3)
 
+You can also find a curated list of awesome packages, articles, and other cool resources from the Wagtail community at [Awesome Wagtail](https://github.com/springload/awesome-wagtail).
 
-More information
-~~~~~~~~~~~~~~~~
+## More information
 
-.. toctree::
-    :maxdepth: 2
+```{toctree}
+:maxdepth: 2
 
-    styleguide
-    general_guidelines
-    python_guidelines
-    ui_guidelines
-    documentation_guidelines
-    documentation-modes
-    security
-    release_process
+styleguide
+general_guidelines
+python_guidelines
+ui_guidelines
+documentation_guidelines
+documentation_modes
+security
+release_process
+```

docs/contributing/python_guidelines.md

@@ -1,81 +1,77 @@
-Python coding guidelines
-========================
+# Python coding guidelines
 
-PEP8
-~~~~
+## PEP8
 
-We ask that all Python contributions adhere to the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ style guide.
-All files should be formatted using the `black <https://github.com/psf/black>`_ auto-formatter. This will be
-run by ``pre-commit`` if that is configured.
+We ask that all Python contributions adhere to the [PEP8](https://www.python.org/dev/peps/pep-0008/) style guide.
+All files should be formatted using the [black](https://github.com/psf/black) auto-formatter. This will be
+run by `pre-commit` if that is configured.
 
-* The project repository includes an ``.editorconfig`` file. We recommend using
-  a text editor with `EditorConfig <https://editorconfig.org/>`_ support to avoid indentation and
-  whitespace issues. Python and HTML files use 4 spaces for indentation.
+-   The project repository includes an `.editorconfig` file. We recommend using
+    a text editor with [EditorConfig](https://editorconfig.org/) support to avoid indentation and
+    whitespace issues. Python and HTML files use 4 spaces for indentation.
 
-In addition, import lines should be sorted according to `isort <https://pycqa.github.io/isort/>`_ 5.6.4 rules.
-If you have installed Wagtail's testing dependencies (``pip install -e '.[testing]'``), you can check your code by
-running ``make lint``. You can also just check python related linting by running ``make lint-server``.
+In addition, import lines should be sorted according to [isort](https://pycqa.github.io/isort/) 5.6.4 rules.
+If you have installed Wagtail's testing dependencies (`pip install -e '.[testing]'`), you can check your code by
+running `make lint`. You can also just check python related linting by running `make lint-server`.
 
-You can run all Python formatting with ``make format``. Similar to linting you can format python/template only files
-by running ``make format-server``.
+You can run all Python formatting with `make format`. Similar to linting you can format python/template only files
+by running `make format-server`.
 
-Django compatibility
-~~~~~~~~~~~~~~~~~~~~
+## Django compatibility
 
-Wagtail is written to be compatible with multiple versions of Django. Sometimes, this requires running one piece of code for recent version of Django, and another piece of code for older versions of Django. In these cases, always check which version of Django is being used by inspecting ``django.VERSION``:
+Wagtail is written to be compatible with multiple versions of Django. Sometimes, this requires running one piece of code for recent version of Django, and another piece of code for older versions of Django. In these cases, always check which version of Django is being used by inspecting `django.VERSION`:
 
-.. code-block:: python
+```python
+import django
 
-    import django
+if django.VERSION >= (1, 9):
+    # Use new attribute
+    related_field = field.rel
+else:
+    # Use old, deprecated attribute
+    related_field = field.related
+```
 
-    if django.VERSION >= (1, 9):
-        # Use new attribute
-        related_field = field.rel
-    else:
-        # Use old, deprecated attribute
-        related_field = field.related
-
-Always compare against the version using greater-or-equals (``>=``), so that code for newer versions of Django is first.
+Always compare against the version using greater-or-equals (`>=`), so that code for newer versions of Django is first.
 
-Do not use a ``try ... except`` when seeing if an object has an attribute or method introduced in a newer versions of Django, as it does not clearly express why the ``try ... except`` is used. An explicit check against the Django version makes the intention of the code very clear.
+Do not use a `try ... except` when seeing if an object has an attribute or method introduced in a newer versions of Django, as it does not clearly express why the `try ... except` is used. An explicit check against the Django version makes the intention of the code very clear.
 
-.. code-block:: python
-
-    # Do not do this
-    try:
-        related_field = field.rel
-    except AttributeError:
-        related_field = field.related
+```python
+# Do not do this
+try:
+    related_field = field.rel
+except AttributeError:
+    related_field = field.related
+```
 
 If the code needs to use something that changed in a version of Django many times, consider making a function that encapsulates the check:
 
-.. code-block:: python
-
-    import django
+```python
+import django
 
-    def related_field(field):
-        if django.VERSION >= (1, 9):
-            return field.rel
-        else:
-            return field.related
+def related_field(field):
+    if django.VERSION >= (1, 9):
+        return field.rel
+    else:
+        return field.related
+```
 
 If a new function has been introduced by Django that you think would be very useful for Wagtail, but is not available in older versions of Django that Wagtail supports, that function can be copied over in to Wagtail. If the user is running a new version of Django that has the function, the function should be imported from Django. Otherwise, the version bundled with Wagtail should be used. A link to the Django source code where this function was taken from should be included:
 
-.. code-block:: python
-
-    import django
+```python
+import django
 
-    if django.VERSION >= (1, 9):
-        from django.core.validators import validate_unicode_slug
-    else:
-        # Taken from https://github.com/django/django/blob/1.9/django/core/validators.py#L230
-        def validate_unicode_slug(value):
+if django.VERSION >= (1, 9):
+    from django.core.validators import validate_unicode_slug
+else:
+    # Taken from https://github.com/django/django/blob/1.9/django/core/validators.py#L230
+    def validate_unicode_slug(value):
             # Code left as an exercise to the reader
             pass
+```
 
-Tests
-~~~~~
+## Tests
 
-Wagtail has a suite of tests, which we are committed to improving and expanding. See :ref:`testing`.
+Wagtail has a suite of tests, which we are committed to improving and expanding. See [](testing).
 
 We run continuous integration to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly.

docs/contributing/release_process.md

@@ -1,67 +1,62 @@
-=========================
-Wagtail's release process
-=========================
+# Wagtail's release process
 
-Official releases
-=================
+## Official releases
 
 Release numbering works as follows:
 
-* Versions are numbered in the form ``A.B`` or ``A.B.C``.
+-   Versions are numbered in the form `A.B` or `A.B.C`.
 
-* ``A.B`` is the *feature release* version number. Each version will be mostly
-  backwards compatible with the previous release. Exceptions to this rule will
-  be listed in the release notes.
+-   `A.B` is the _feature release_ version number. Each version will be mostly
+    backwards compatible with the previous release. Exceptions to this rule will
+    be listed in the release notes.
 
-* ``C`` is the *patch release* version number, which is incremented for bugfix
-  and security releases. These releases will be 100% backwards-compatible with
-  the previous patch release. The only exception is when a security or data
-  loss issue can't be fixed without breaking backwards-compatibility. If this
-  happens, the release notes will provide detailed upgrade instructions.
+-   `C` is the _patch release_ version number, which is incremented for bugfix
+    and security releases. These releases will be 100% backwards-compatible with
+    the previous patch release. The only exception is when a security or data
+    loss issue can't be fixed without breaking backwards-compatibility. If this
+    happens, the release notes will provide detailed upgrade instructions.
 
-* Before a new feature release, we'll make at least one release candidate
-  release. These are of the form ``A.BrcN``, which means the
-  ``Nth`` release candidate of version ``A.B``.
+-   Before a new feature release, we'll make at least one release candidate
+    release. These are of the form `A.BrcN`, which means the
+    `Nth` release candidate of version `A.B`.
 
 In git, each Wagtail release will have a tag indicating its version number.
 Additionally, each release series has its
-own branch, called ``stable/A.B.x``, and bugfix/security releases will be
+own branch, called `stable/A.B.x`, and bugfix/security releases will be
 issued from those branches.
 
-.. glossary::
+**Feature release**
 
-  Feature release
-    Feature releases (A.B, A.B+1, etc.) happen every three months
-    -- see `release process <#release-process>`__ for details. These releases will contain new
-    features and improvements to existing features.
+Feature releases (A.B, A.B+1, etc.) happen every three months
+-- see [release process](release-process) for details. These releases will contain new
+features and improvements to existing features.
 
-  Patch release
-    Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix
-    bugs and/or security issues.
+**Patch release**
 
-    These releases will be 100% compatible with the associated feature release,
-    unless this is impossible for security reasons or to prevent data loss.
-    So the answer to "should I upgrade to the latest patch release?" will always
-    be "yes."
+Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix
+bugs and/or security issues.
 
-  Long-term support release
-    Certain feature releases will be designated as long-term support (LTS)
-    releases. These releases will get security and data loss fixes applied for
-    a guaranteed period of time, typically six months.
+These releases will be 100% compatible with the associated feature release,
+unless this is impossible for security reasons or to prevent data loss.
+So the answer to "should I upgrade to the latest patch release?" will always
+be "yes."
 
+**Long-term support release**
 
-Release cadence
-===============
+Certain feature releases will be designated as long-term support (LTS)
+releases. These releases will get security and data loss fixes applied for
+a guaranteed period of time, typically six months.
 
-Wagtail uses a loose form of `semantic versioning <https://semver.org/>`_.
+## Release cadence
+
+Wagtail uses a loose form of [semantic versioning](https://semver.org/).
 SemVer makes it easier to see at a glance how compatible releases are with each
 other. It also helps to anticipate when compatibility shims will be removed.
 It's not a pure form of SemVer as each feature release will continue to have a
 few documented backwards incompatibilities where a deprecation path isn't
 possible or not worth the cost.
 
-Deprecation policy
-==================
+## Deprecation policy
 
 A feature release may deprecate certain features from previous releases. If a
 feature is deprecated in feature release A.B, it will continue to work in
@@ -72,71 +67,67 @@ over at least 2 feature releases.
 So, for example, if we decided to start the deprecation of a function in
 Wagtail 1.4:
 
-* Wagtail 1.4 will contain a backwards-compatible replica of the function which
-  will raise a ``RemovedInWagtail16Warning``.
+-   Wagtail 1.4 will contain a backwards-compatible replica of the function which
+    will raise a `RemovedInWagtail16Warning`.
 
-* Wagtail 1.5 will still contain the backwards-compatible replica.
+-   Wagtail 1.5 will still contain the backwards-compatible replica.
 
-* Wagtail 1.6 will remove the feature outright.
+-   Wagtail 1.6 will remove the feature outright.
 
 The warnings are silent by default. You can turn on display of these warnings
-with the ``python -Wd`` option.
-
+with the `python -Wd` option.
 
-Supported versions
-==================
+## Supported versions
 
 At any moment in time, Wagtail's developer team will support a set of releases to
 varying levels.
 
-* The current development ``main`` will get new features and bug fixes
-  requiring non-trivial refactoring.
-
-* Patches applied to the ``main`` branch must also be applied to the last feature
-  release branch, to be released in the next patch release of that feature
-  series, when they fix critical problems:
+-   The current development `main` will get new features and bug fixes
+    requiring non-trivial refactoring.
 
-  * Security issues.
+-   Patches applied to the `main` branch must also be applied to the last feature
+    release branch, to be released in the next patch release of that feature
+    series, when they fix critical problems:
 
-  * Data loss bugs.
+    -   Security issues.
 
-  * Crashing bugs.
+    -   Data loss bugs.
 
-  * Major functionality bugs in newly-introduced features.
+    -   Crashing bugs.
 
-  * Regressions from older versions of Wagtail.
+    -   Major functionality bugs in newly-introduced features.
 
-  The rule of thumb is that fixes will be backported to the last feature
-  release for bugs that would have prevented a release in the first place
-  (release blockers).
+    -   Regressions from older versions of Wagtail.
 
-* Security fixes and data loss bugs will be applied to the current ``main``, the
-  last feature release branch, and any other supported long-term
-  support release branches.
+    The rule of thumb is that fixes will be backported to the last feature
+    release for bugs that would have prevented a release in the first place
+    (release blockers).
 
-* Documentation fixes generally will be more freely backported to the last
-  release branch. That's because it's highly advantageous to have the docs for
-  the last release be up-to-date and correct, and the risk of introducing
-  regressions is much less of a concern.
+-   Security fixes and data loss bugs will be applied to the current `main`, the
+    last feature release branch, and any other supported long-term
+    support release branches.
 
+-   Documentation fixes generally will be more freely backported to the last
+    release branch. That's because it's highly advantageous to have the docs for
+    the last release be up-to-date and correct, and the risk of introducing
+    regressions is much less of a concern.
 
 As a concrete example, consider a moment in time halfway between the release of
 Wagtail 1.6 and 1.7. At this point in time:
 
-* Features will be added to ``main``, to be released as Wagtail 1.7.
+-   Features will be added to `main`, to be released as Wagtail 1.7.
 
-* Critical bug fixes will be applied to the ``stable/1.6.x`` branch, and
-  released as 1.6.1, 1.6.2, etc.
+-   Critical bug fixes will be applied to the `stable/1.6.x` branch, and
+    released as 1.6.1, 1.6.2, etc.
 
-* Security fixes and bug fixes for data loss issues will be applied to
-  ``main`` and to the ``stable/1.6.x`` and ``stable/1.4.x`` (LTS) branches.
-  They will trigger the release of ``1.6.1``, ``1.4.8``, etc.
+-   Security fixes and bug fixes for data loss issues will be applied to
+    `main` and to the `stable/1.6.x` and `stable/1.4.x` (LTS) branches.
+    They will trigger the release of `1.6.1`, `1.4.8`, etc.
 
-* Documentation fixes will be applied to ``main``, and, if easily backported, to
-  the latest stable branch, ``1.6.x``.
+-   Documentation fixes will be applied to `main`, and, if easily backported, to
+    the latest stable branch, `1.6.x`.
 
-Supported versions of Django
-============================
+## Supported versions of Django
 
 Each release of Wagtail declares which versions of Django it supports.
 
@@ -146,39 +137,35 @@ all following versions of Django.
 For example, consider a moment in time before release of Wagtail 1.5
 and after the following releases:
 
-* Django 1.8 (LTS)
-* Django 1.9
-* Wagtail 1.4 (LTS) - Released before Django 1.10 and supports Django 1.8 and 1.9
-* Django 1.10
+-   Django 1.8 (LTS)
+-   Django 1.9
+-   Wagtail 1.4 (LTS) - Released before Django 1.10 and supports Django 1.8 and 1.9
+-   Django 1.10
 
 Wagtail 1.5 will support Django 1.8 (LTS), 1.9, 1.10.
 Wagtail 1.4 will still support only Django 1.8 (LTS) and 1.9.
 
-.. _release-process:
+(release-process)=
 
-Release process
-===============
+## Release process
 
-Wagtail uses a `time-based release schedule <https://github.com/wagtail/wagtail/wiki/Release-schedule>`_,
+Wagtail uses a [time-based release schedule](https://github.com/wagtail/wagtail/wiki/Release-schedule),
 with feature releases every three months.
 
 After each feature release, the release manager will announce a timeline for
 the next feature release.
 
-Release cycle
--------------
+### Release cycle
 
 Each release cycle consists of three parts:
 
-Phase one: feature proposal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Phase one: feature proposal
 
 The first phase of the release process will include figuring out what major
 features to include in the next version. This should include a good deal of
 preliminary work on those features -- working code trumps grand design.
 
-Phase two: development
-~~~~~~~~~~~~~~~~~~~~~~
+#### Phase two: development
 
 The second part of the release schedule is the "heads-down" working period.
 Using the roadmap produced at the end of phase one, we'll all work very hard to
@@ -187,10 +174,9 @@ get everything on it done.
 At the end of phase two, any unfinished features will be postponed until the
 next release.
 
-At this point, the ``stable/A.B.x`` branch will be forked from ``main``.
+At this point, the `stable/A.B.x` branch will be forked from `main`.
 
-Phase three: bugfixes
-~~~~~~~~~~~~~~~~~~~~~
+#### Phase three: bugfixes
 
 The last part of a release cycle is spent fixing bugs -- no new features will
 be accepted during this time.
@@ -208,17 +194,16 @@ candidate - this ensures that translators have the full period between the relea
 candidate and the final release to bring translations up to date. Translations
 will be re-imported immediately before the final release.
 
-In parallel to this phase, ``main`` can receive new features, to be released
-in the ``A.B+1`` cycle.
+In parallel to this phase, `main` can receive new features, to be released
+in the `A.B+1` cycle.
 
-Bug-fix releases
-----------------
+### Bug-fix releases
 
 After a feature release (e.g. A.B), the previous release will go into bugfix
 mode.
 
-The branch for the previous feature release (e.g. ``stable/A.B-1.x``) will
-include bugfixes. Critical bugs fixed on ``main`` must *also* be fixed on the
+The branch for the previous feature release (e.g. `stable/A.B-1.x`) will
+include bugfixes. Critical bugs fixed on `main` must _also_ be fixed on the
 bugfix branch; this means that commits need to cleanly separate bug fixes from
-feature additions. The developer who commits a fix to ``main`` will be
+feature additions. The developer who commits a fix to `main` will be
 responsible for also applying the fix to the current bugfix branch.

docs/contributing/security.md

@@ -1,7 +1,7 @@
 # Reporting security issues
 
 ```{note}
-   Please report security issues **only** to [security@wagtail.org](mailto:security@wagtail.org).
+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/contributing/styleguide.md

@@ -1,19 +1,18 @@
-.. _styleguide:
+(styleguide)=
 
-UI Styleguide
-=============
+# UI Styleguide
 
 Developers working on the Wagtail UI or creating new UI components may wish to test their work against our Styleguide, which is provided as the contrib module "wagtailstyleguide".
 
-To install the styleguide module on your site, add it to the list of ``INSTALLED_APPS`` in your settings:
+To install the styleguide module on your site, add it to the list of `INSTALLED_APPS` in your settings:
 
-.. code-block:: python
-
-    INSTALLED_APPS = (
-        ...
-        'wagtail.contrib.styleguide',
-        ...
-    )
+```python
+INSTALLED_APPS = (
+    # ...
+    'wagtail.contrib.styleguide',
+    # ...
+)
+```
 
 This will add a 'Styleguide' item to the Settings menu in the admin.